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THE BUILDING 
BLOCKS OF VISUAL 
DEVELOPMENT. 





The elements of next genera- 
tion applications are found in the 
components of the Microsoft’ 
Visual C++” development system, 
version 1.5 today. 

Innovative wizard technology 
allows you to seamlessly meld 
components into sophisticated appli- 
cations, in weeks not months. Just 
remember this simple equation: 
MFC 2.5, OLE 2.0, ODBC. 

That’s a perfect formula for 


building and reusing components. 


At the nucleus is MFC 2.5 


(Microsoft Foundation Class Libra- 
ries), the standard API for Windows: 


The new OLE (Object Linking 
and Embedding) classes make it 
easier than ever to implement OLE’ 
unprecedented integration power, 
new drag-and-drop features, visual 
editing and OLE automation. 
In all, it provides more than 19,000 
lines of code you want, but wont 
have to write or rewrite. 

In addition, the new ODBC 


(Open Database Connectivity) 


classes provide access to major 
databases and data binding without 
coding. It’s a powerful new plat 
form for creating high-performance 
database applications. 

Best of all, your 16-bit MFC 
applications are portable to the 
Windows NT“ operating system and 
future versions of Windows. Now 
that’s good chemistry. 

If you want the latest tools for 
the latest Windows technology, ask 
for Microsoft Visual C++ 1.5. 

Call us now at (800) 434-3980 
and we'll make you a catalyst for 
change today and into the future 


of Windows operating systems. 





New 16-bit version 1.5 joins the Visual C++ 
family of development systems for Windows 
and Windows NT. 


Microsoft 





© 1993 Microsoft Corporation. All rights reserved. In the 50 United States, call (800) 434-3980; customers in Canada, call (800) 563-9048; outside the U.S. 
and Canada, call your local Microsoft subsidiary or (206) 936-8661. Microsoft is a registered trademark and Visual C++, Windows and Windows NT are 


trademarks of Microsoft Corporation. 
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BINARY-DATA PORTABILITY 13 
by José Luu 

The DDR compiler José presents here makes it possible for you to create truly portable 

tools for handling binary-data representations between different environments. This 

means you can create a single source-code base without having to add elaborate data- 

translation code. 


THE WRAPI TOOLKIT 26 
by Gregory C. Sarafin 

WRAPI is a language-independent API that generates language-specific libraries. The 

host languages it supports include C, Clipper, FoxPro (DOS and Windows), Visual Basic 

(DOS and Windows), Pascal, Clarion, Fortran, and more. 


MULTIPLATFORM INI FILES 36 
by Joseph J. Graf 

Joe’s multiplatform implementations of the the Windows GetPrivateProfileString(), 
GetPrivateProfileInt(), and WritePrivateProfileString() functions support DOS and 

UNIX, too. 


PORTABILITY BY DESIGN 40 
by Michael Ross 

Michael lifts the hood on MetaWare’s compiler technology, sharing the mapping 

structures and techniques that make porting the compiler from one platform to another 

a relatively simple task. 


UNICODE AND SOFTWARE GLOBALIZATION 46 
by David Van Camp 

Writing code for international markets requires an understanding of the Unicode 

standard. David examines the standard and discusses how you go about implementing 

Unicode support. 


WRITING NON-SCSI CD-ROM DEVICE DRIVERS 102 
by Sing Li 

Compatibility is one of the main reasons why environments such as the Windows NT 

and OS/2 2.x operating systems support SCSI-based CD-ROM hardware. However, if you 

want to use non-SCSI CD-ROM drives with them, you'll have to write your own device 

drivers. This article discusses how you code those drivers for Windows NT. 





by Brian Sawert 


EMBEDDED SYSTEMS 


by Dan Troy 











Thanks to Corinne H. Godon of Neuron Data 
(Palo Alto, CA) for helping with the systems and software 
shown on the cover and elsewhere in this issue. 


THE ADVANCED SCSI PROGRAMMING INTERFACE 154 


The advanced SCSI programming interface, available for DOS, OS/2, 
Novell NetWare, and other operating systems, provides a high-level function 
set that’s easy to use because it hides the inner workings of SCSI protocol. 


EMULATING NON-DOS SYSTEMS UNDER MS-DOS 52 


Dan describes a table-mapping mechanism to handle operating-system functions and 
their associated parameters. This allowed him to emulate non-DOS systems while 
running on DOS-based PC development environments. 
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NETWORKED SYSTEMS 


CROSS-PLATFORM DEVELOPMENT WITH VISUAL C++ 64 
by Chane Cullens 

Although generally thought of as a DOS/Windows development tool, Microsoft’s Visual 

C++ and the Microsoft Foundation Class library can be used for cross-platform 

development. Chane discusses how you can use them to write portable code, 

whether you're coding for Windows, UNIX, NT, Macintosh, or whatever. 


EXAMINING ROOM 


DATABASE DEVELOPMENT AND VISUAL BASIC 3.0 /4 





by Ken North 
Although Microsoft calls it “Visual Basic 3.0 Professional Edition,” you could just as 
easily refer to the package as “the Visual Basic Database Edition” because of the FORUM 
available database tools and functionality. Ken examines the Visual Basic 3.0 
environment and database tools, presenting a multimedia database app in the process. EDITORIAL 6 
by Jonathan Erickson 
PROGRAMMER'S WORKBENCH LETTERS 10 
SAUEMCEMAMRRGSGRGRAR «OU(«‘(*é«=‘“‘ .:;*é‘ ‘CS by you 
oe — DOS TO WINDOWS 8 SWAINE'S FLAMES 168 
WinGate’s client/server API minimizes your recoding efforts when moving from DOS to by Michael Swaine 
Windows. Walter uses the tool to build a simple client/server database application. 
PROGRAMMER’S 
COLUMNS SERVICES 
OF INTEREST 162 
PROGRAMMING PARADIGMS 115 bi Meiboa Bi Bers 
by Michael Swaine 
Last year, Apple introduced the Newton MessagePad, along with a new user-interface SOURCE CODE 
model, new development platform, and new object-oriented language. Michael discusses 
what Newton really is (and isn’t), the first Newton Platform Development Conference, AVAILABILITY 


and the Newton Toolkit, and speculates on the unique challenges Newton presents. 
As a service to our readers, all source code 


C PROGRAMMI ] 2| is available on a single disk and online. To 
oe om order the disk, send $14.95 (California 


by Al Stevens d 4d eal to Dr Dobb’ 
Al takes a break from the rigors of coding to mull over software patents, electronic ee 
books, and the mysteries of placing a long (but not too long) distance phone call in ee 
hay 94402, call 1-415-358-9500, x240, or use 
Silicon Valley. your credit card to order by fax, 1-415-358- 
9749. Specify issue number and disk 
ALGORITHM ALLEY 27 ae is also available through the 
edited by Tom Swan DD] Forum on CompuServe (type GO ~ 
Ernie Deel shares a data-compression technique that uses pattern recognition to quickly DDJ), via anonymous FTP from site 
achieve efficient compression ratios. ftp.mv.com (192.80.84.1) in the /pub/ddj 
directory, and through M&T Online, a free 
UNDOCUMENTED CORNER 133 service accessible via direct dial at 1-415- 
edited by Andrew Schulman 358-8857 (1200/2400 baud, 8-N-1). 
Alex Shmidt presents a technique for dynamically loading and unloading VxDs without 
having to use VXDLDR or a VxD file. This is, in fact, a general technique for calling any NEXT M () NTH 
32-bit Ring 0 code from a normal Ring 3 Windows program. © 
Algorithms are the fundamental buildin 
PROGRAMMER’S BOOKSHELF 14] ede of software. In April, we'll ; 
by Jonathan Erickson examine a variety of unique and useful 
Like it or not, self-help programming and legal books go hand-in-hand. This month, we algorithms — including the exciting 
examine two new legal self-help books, Software Development: A Legal Guide, and The wavelet packet transform—and report on 
Software Developer's and Marketer's Legal Companion. a high-level algorithms conference. 
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Save Disk Space 





PKZIP version 2.0 


PC WORLD 


PKWARE®* introduces the next generation of its award 
winning compression utility. PAZIP 2.0 yields greater 
performance levels than achieved with previous releases 
of the software. PKZIP compresses and archives files. 
This saves disk space and reduces file transfer time. 


Software developers! You can significantly reduce 

product duplication costs by decreasing the number of 
WORLD CLASS disks required to distribute your applications. Call for 
AWARD Distribution License information. 


Put Your Executables on a Diet 


Software developers! Save disk space and 
media costs with smaller executables. You can 
distribute your software in a compressed form 
with PKLITE Professional.” PKLITE Professional 
dives you the ability to compress files so that 
they cannot be expanded by PKLITE.™ This 
discourages reverse engineering of your 
programs. 





PKLITE Increases your valuable disk space by compressing DOS 
executable (.EXE and .COM) files by an average Of 45%. The operation of 
PRLITE is transparent, all you will notice is more available disk space! 


Compression for YOUR Application 


The PAWARE Data Compression Library ™ 
allows you to incorporate data 
Compression technology into your 
software applications. The application 
program Controls all the input and 
output of data, allowing data to be 
compressed or extracted to or from any 
device or area Of memory. 





All Purpose Data Compression Algorithm Compresses ASCII or binary data 
quickly. The routines can be used with many popular DOS lanquages. A 
Windows DLL and an OS/2 32-bit version is also available! 


@) 





\ Saw INC. 


@ 


9025 NN. Deerwood Drive Brown Deer, WI 53223-2437 
(414) 354-8699 Fax (414) 354-8559 


FRKWARE Data Compression Library for DOS $275 PKWAKE Data Compression Library for OS/2 $350 


FAWARE Data Compression Library DLL for Windows $350 
PRZIP $47.00 PRLITE $46.00 PALITE Professional 5146.00 
Flease add $5.00 S&H per package in the US & Canada, $11.25 overseas. 
Wisconsin residents add appropriate state sales tax & county Sales tax. 
Visa and Mastercard accepted, no COD orders. 
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INTRODUCING SYMANTEC 
(++ PROFESSIONAL DESIGNED BY 
MICROSOFT AND BORLAND C++ USERS. 


We asked questions. 
We listened. And we took 
what we learned from 
Microsoft and Borland 
C++ users and created 
a better way for you to 
develop applications. 


The best compiler. 
And the best linker. 


Microsoft users hate 
slow compilers. Borland 
users hate slow, fat code. 
So we made Symantec 
C++ Professional 6.0 
faster and more efficient. 

But our one-pass compiler isn’t just 
faster — it produces faster applications. 
Thanks to powerful global and local 
optimizations. And some unique C++ 
optimizations you won't find anywhere 
else. We've also included OPTLINK, 
absolutely the fastest linker you can buy. 


The best environment. 


Symantec C++ is the first 
development system to fully integrate 
editing, compiling, debugging and 
version control in a completely new 
and graphical Integrated Development 
and Debugging Environment (IDDE). 
This breakthrough new IDDE is packed 
with graphical tools, a great new 
resource editor and drag-and- 
drop capabilities. 


The best visual tools. 


Using technology developed 
for Symantec by Blue Sky 


Symantec C++ is available in both 
Professional and Standard versions. 












ss: oe 
Workspace Wind 





Software, Symantec C++ gives you the 
world’s most sophisticated visual tools. 
This is what Microsoft Visual C++ 
should have been. 


Win32s from the leader 
in 32-bit compilers. 


Win32s is free in every box. Create 
true 32-bit applications that run 
unchanged under both Windows 8.1 
and Windows NT. Develop and debug 
apps on your existing Windows system. 


It’s easy to switch. 


Symantec C++ is highly compatible 
with Microsoft and Borland C++. So 
there’s no reason to wait. 
We've also included the 
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complete Microsoft 
Foundation Classes 2.0 
as well as support for 
Microsoft Visual Basic 
controls. 


Order today. 


Symantec C++ 
Professional 6.0 is now 
priced at just $499* 

But if you are already a 
Microsoft or Borland 
user, we have a special 
upgrade offer of just 
$199.95.** A 60% savings. 

See your dealer. Or 
call 1-800-453-1077 ext. AP81 and 
order now. Symantec C++ Professional 
6.0 everything a Microsoft or Borland 
C++ user could want. 


Get today’s best C++. 
And two tickets to Hawaii. 


Two awesome environments in every box. 
Along with our incredibly powerful 
IDDE, you'll also find a coupon redeemable 
for two airline tickets to Hawai 
in every copy of Symantec C++ Professional 
or competitive upgrade. 


This coupon is redeemable for a travel certificate that entitles 
you to receive from Travel Reservations, roundtrip airline 
tickets for two to Honolulu, Hawati upon the purchase of seven 
nights hotel accommodations with an estimated total cost of 
$826 to $1,806. Prices may be subject to reasonable changes 
(i.e., inflation) prior to confirmation. Prices may vary 
depending on times and dates of departure. Some restrictions 
do apply. For complete FAX details, dial 1-500-554-4403, select 
option #1, document #443. 


WAVINNGNSON 





*Suggested retail price. Actual price may vary. **Upgrade offer plus 


shipping, handling and applicable tax. Offer price in U.S. dollars. 
Valid in U.S. and Canada only. For more information in Europe, 
call 31-71-353111. In Australia, call 61-2-879-6577. In Canada, call 1- 
500-667-8661. Everywhere else, call 408-252-3570. Symantec C++ ts a 
registered trademark of Symantec Corporation. All other products 
are trademarks or registered trademarks of their respective holders. 


©1993 Symantec Corporation. All rights reserved. 


Will Reverse 
Engineering 
Take a Step 

Backwards ? 





EDITORIAL 


programmers dive into at one time or another, whether with their own or someone else’s 

code, whether they want to or not. The courts have defined reverse engineering as “a fair and 
honest means of... starting with the known product and working backwards to divine the process 
which aided in its development or manufacture.” As for software reverse engineering, the courts 
go on to say it’s “the process of starting with a finished product and working backwards to 
analyze how the product operates or it was made.” Reverse-engineering expert Andy Johnson- 
Laird points out that both definitions focus on the reverse-engineering process, not the resulting 
product, adding that “the static and dynamic examinations of a computer program are the only 
two activities that are viewed by programmers as being reverse engineering.” 

Even though it’s protected by copyright law, reverse engineering is nonetheless under fire. In fact, 
if the federal government— pressured by influential software companies— gets its way, reverse 
engineering may be limited to inspection of software you write, and outlawed in all other instances. 

Of course, reverse engineering isn’t unique to software development. When an anonymous 
caveman fashioned the first wheel, an enterprising hardware guy in the next cave probably 
figured out how to turn a similar hunk of rock into a similar cylinder. From computer chips to 
potato chips, every industry engages in reverse engineering. Still, it is software reverse 
engineering that’s at the eye of the storm. 

Much of the current furor over software reverse engineering revolves around international 
intellectual-property protection. Recent changes in European Community law allow you to reverse 
engineer when you want to create software that interoperates with, but does not replace, the 
original program. In light of the EC provisions (not to mention U.S. cases such as Sega vs. 
Accolade and Atari vs. Nintendo, both involving reverse engineering), Japan is re-examining its 
intellectual-property laws, and U.S. software companies fear that the Japanese will be equally 
lenient when it comes to reverse engineering. Spurred on by IBM, Microsoft, Apple, and others, 
U.S. trade representatives have sent letters to the Japanese expressing “grave concern” over the 
possibility that Japan will relax reverse engineering laws. 

Confused by the intellectual-property debate, the knee-jerk reaction of most developers is to 
prohibit reverse engineering. Take a look at the shrink-wrap licenses of software on your shelf 
(including that of the Dataware search/retrieval engine at the heart of the Dr. Dobb’s/CD) and 
you'll find what Walter Oney (who writes this month’s “Programmer’s Workbench”) calls 
“draconian” license restrictions forbidding you to modify, translate, adapt, reverse engineer, 
decompile, or disassemble the software. Amazingly, you sometimes don’t even get to read the 
license until after breaking the seal. Of course, the validity of this shrink-wrap ban on reverse 
engineering has yet to be tested in court, although both Illinois and Louisiana have statutes 
legalizing such prohibitions. 

The limits of reverse engineering may eventually be determined by a pivotal court case in 
which Microsoft claims that Stac Electronics reverse engineered betas of MS-DOS 6.0. It’s ironic 
that, on one hand, Microsoft enjoins reverse engineering of its software, while on the other 
implicitly condoning the process by publishing articles such as Matt Pietrek’s excellent “A Look 
under the Hood of the Windows 3.1 Global Heap and the Functions that Maintain It’ in Microsoft 
Systems Journal (March, 1993). While he doesn’t use the “R” word in the article, Pietrek clearly 
states that the article was adapted from his book Windows Internals, where he openly 
acknowledges that the information was gained via reverse engineering. 

This isn’t to say that the right to reverse engineer software hasn’t been abused, However, 
reverse engineering is too difficult, time consuming, and expensive for software thieves (the 
convenient targets of those who would ban reverse engineering) to bother with. It’s more cost- 
effective for pirates just to copy software. 

There are good reasons for going to the trouble of reverse engineering: recycling old software 
for new systems, rooting out bugs coded by programmers no longer around, and ensuring 
compatibility with existing software. Perhaps even more important in these days of intellectual- 
property litigation, reverse engineering provides a way to identify patented technology so that you 
can dvoid infringing upon it. * 

In the long run, U.S. companies may do themselves more harm than good by stifling reverse 
engineering, particularly if it’s restricted in the U.S. and legal elsewhere in the world. In the short 
term, software companies have to realize that they can’t have it both ways: If you don’t want 
programmers stepping all over your intellectual property, you can’t bar them from discovering 
what that property is— and reverse engineering is the best way to find out. 


Palin 


Jonathan Erickson 
editor-in-chief 


R everse engineering is a fundamental software development process which almost all 
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Visual Development 


The Phase3 visual development environment 
provides a comprehensive suite of tools for 
screen creation. All standard Windows 
screen objects — push buttons, radio buttons, 
dialog boxes, etc. — are selectable from icon 
bars and are dynamically placed and sized 
on the screen as appropriate for the 
application. Standard Windows APIs are 
available from list boxes and are supported 
with on-line documentation. 





Phase3 Database 


Phase3 includes a relationally complete 
database supplied as a Windows DLL. The 
database supports complex data relation- 
ships and access and data manipulation by 
any language through a comprehensive 
suite of supplied database routines. 
Database integrity is enhanced with 
rollback recovery and transaction control. 
The Phase3 data dictionary simplifies data 
model definition and maintenance. 





Query and Reporting 

The Report Writer includes standard 
features like flexible headers, footers, free 
text, calculated fields, sort group sections 
and breaks, and subtotals. Reports can also 
include bitmaps of drawings and photo- 
graphic images. Queries are executed with 
the Database Browser which also allows 
data entry and manipulation. Railway 
diagrams assist in query creation, prompt- 
ing the user for appropriate selections and 
eliminating syntactical errors. 
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{ MONEY-BACK \ 


Royalty-Free Applications 


Windows is a trademark of Microsoft Corporation. Turbo Pascal 
for Windows and Borland Pascal 7.0 are trademarks of Borland 
International, Inc. All other trademarks or service marks are 
recognized as the property of their respective owners. 
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Develop 








indows Applications 
Quickly and Easily 


Phase3 Has Everything You Need 
















Lower CASE, E-R Modeling 


Phase3 automates logical data model design 
with Entity-Relationship modeling. After a 
user describes entity relationships graphi- 
cally and enters field descriptions, Phase3 
generates the physical database based on an 
analysis of the entity relationships. Phase3 
automatically includes foreign keys in 
appropriate tables and restructures the 
database as requirements change. Phase3 
suggests appropriate referential integrity 
constraints to be enforced at runtime. 





Hierarchy Chart 


Phase3 maintains a graphical map of an entire 
application. The Hierarchy Chart includes all 
windows, dialogs, reports, and code routines. 
To access the underlying C or Pascal source 
code, simply point-and-click on any node. 
Phase3 generated source is easily accessed 
and extended with user written routines. User 
code is preserved even if an application is 
regenerated. The Hierarchy Chart and E-R 
Diagram provide instant core documentation 
for an application. 












Help Generator 


The Phase3 Help Generator allows the easy 
creation of a complete Windows application 
help subsystem including context sensitive 
on-line help. The Help Generator includes its 
own text editor that gives complete control 
over the content, appearance, and branching 
logic through highlighted trigger text. Phase3 
generates a Windows compatible file with an 
‘“ HLP” extension that is then accessible 
from within the Phase3 created application. 
No other external tools are required. 














Order Now 


800-851-5650 


Or Call for Free Demo Disk 
Fax (805) 641-9083 


CALL NOW FOR COMPETITIVE UPGRADE PRICING 

















“ .. a thoroughly remarkable product... 

very impressive” 
Jeff Duntemann 
PC Techniques 
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“! was very impressed with Phase3, and using it 
made me wish | had learned Windows programming 
with a tool like this. Now that | know what it has to 
offer, I’ll probably use it to build the frame for most 
of my programs.” 
L. John Ribar 
Windows Tech Journal 
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“Phase3 hides the complexity of Windows program- 
ming but still allows an experienced programmer to 
drill down and extend generated C or Pascal source 
code, providing ultimate control.” 
Randy Goodhew 
Computer Software Columnist 
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“Phase3 takes an intuitive, innovative approach to 
developing Windows applications. It’s a pleasure to 
work with and has greatly boosted our productivity. 
One of the most important issues for us is that their 
technical support is excellent.” 
Reuben Halevi 
ISoft D&M 
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“It’s easy to put together an application with Phase3 
— everything’s integrated. And the Phase3 database 
is terrific. It’s closer to true relational than anything 
we ve found.” 
Michael Erickson 
Prism Business Solutions 


Can you really 
look us in the face and 


say you dont need 
better code 


management? 


SPARCworks Manager— Parallel Make— FileMerge— CheckPoint— 
Coordinate your development Dramatically accelerate Graphically compare and Capture complete project 
sessions and tools. User extensible. —_ project builds by leveraging merge source code. releases for later retrieval. 
the power of your compute Automatically merge con- 
server. currently modified files. 
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Code Manager— Compatible— Version Tool— 

Easily organize and integrate work from Begin using without any special Accelerate version control. 
multiple developers, sites, and platforms. preparation or administrative Graphically view source file history 
Automatically track and inform of con- requirements. as well as concurrent modifications. 


flicting source code changes. 





Because this is the new face of software develop- 
ment — integrated, organized, productive, and very, 
very easy to use. 

It’s called SPARCworks"/TeamWare for the Solaris” 
operating environment. 

And it’s from SunPro; the software development 
arm of Sun Microsystems, Inc? 

What makes our SPARCworks/TeamWare 
products so great? Let us answer that question 


with a few of our own. 





How would you like to have 





multiple developers working on 












the same source base without 





getting in each other's way? 
Or how about doing 


source code development, 


= And manage more than one release 







at a time, with code coming from 
different locations? 
Perhaps building project 


components in parallel and inte- 


Without SPARC works/TeamWare, 
everybody on your team might as 
well be locked in their own rooms. 


grating them later appeals to you? 

We thought so. 

You see, SPARCworks/TeamWare can do all that 
and more. Because it was specifically designed to solve 
the problems of today’s complex, multi-developer, 
multi-site, multi-platform development projects. 

No matter how big or small those projects are. 

SPARCworks/TeamWare works with the 
SPARCworks development environment to be totally 
scalable and extensible — from small groups to large 
ones, across geographically distributed sites, and 


disparate platforms. 




















development environment 
¢Compatible with C, C++, 
Pascal, FORTRAN, and Ada * Supports 
both Solaris land Solaris 2 operating environments 
¢ Graphical tracking of multiple releases for easy 
integration and release management * Graphical inspection and 
manipulation of multiple source file versions * Captures complete 
project source file configuration * Compares and merges con- 
current source file modifications * Accelerates project 
builds ¢ Coordinates and manages individual 
session tasks ¢ ProWorks"/TeamWare 
available for Solaris development on 
x86 platforms * Manages 
code over heterogeneous 
networks 


It’s also customizable to each developer's or team’s 
way of working, right down to specific operations. 

Which brings us to the next point. 

SPARCworks/TeamWare builds on standards your 
developers already know and use: the UNIX® SCCS 
utilities, NFS° and X window system utilities. So there's 
no ramp-up time, no new system administration, 
no conversion, and no special databases. 
You're ready to run as soon as you load it. 

What’s more, because 

SPARCworks/TeamWare uses a 
graphical approach, developers 
can work in parallel, and 
actually see what they — 
and everybody else—are 
doing, all at the same time. 


And what would you 





expect to pay for all this? 
A lot less than you’d guess. 
Under $1,000 a seat. 
Call us at 1-800-2SUNPRO for a copy 
of the SPARCworks/TeamWare Solutions Guide 


including real life success stories 











from SPARCworks/TeamWare users, Kearny eh/ 
or our 30-day Try and Buy CD Mide 


which lets you try SPARCworks/ 
TeamWare before you buy it. 

So why choose between crude | 
version control tools on one end or overly complex 
(and expensive) configuration management systems 
on the other? 

Especially now that you’ve come face to face with 


something better. 


& SunPro 


A Sun Microsystems, Inc. Business 


SunPro, 2550 Garcia Ave., Mountain View, CA 94043-1100. Sun, the Sun logo, Sun Microsystems, SunPro, the SunPro logo, ProWorks, NFS and Solaris, are trademarks or registered trademarks of Sun Microsystems, Inc. 
All SPARC trademarks, including the SCD Compliant logo, are trademarks or registered trademarks of SPARC International, Inc. SPARCompiler, and SPARCworks are licensed exclusively to Sun Microsystems, Inc. 
Products bearing the SPARC trademark are based on an architecture developed by Sun Microsystems, Inc. UNIX is a registered trademark of UNIX System Laboratories. 

All other products or services mentioned herein are trademarks of their respective owners. © 1994 Sun Microsystems, Inc. 
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Comparing Object-oriented Languages 
Dear DDJ, 

Referring to “Comparing Object-orient- 
ed Languages” by Michael Floyd (DDj, 
October 1993), lines of code (LOC) is 
not at all a poor measure of program- 
mer productivity. On the contrary, it is 
an excellent measure of unprofession- 
al and careless programming. 

For example, if a certain piece of 
code can be done in 100 lines in two 
days (50 LOC/day), and someone does 
it in 1000 lines in four days (250 
LOC/day), he isn’t five times more pro- 
ductive — he’s 50 percent less produc- 
tive. The elapsed time is double, and 
the product is ten times larger with the 
corresponding additional costs for ver- 
ification, distribution, and maintenance. 

Assuming that these additional costs 
are half the cost of the project, and that 
they grew just a factor of 5 because the 
larger code is simpler (which is not 
necessarily true), the cost of the pro- 
ject is now three times what it should 
have been. 

Professor E.W. Dijkstra once rightly 
said that programmers should be charged 
for every line of code they write, rather 
than get paid for it. 

If you look at the numbers in Table 
1 of the article, someone whose pay is 
based on LOCs would think that the 
“best” object-oriented language is Eif- 
fel. Assuming experienced program- 
mers require about the same effort, the 
Eiffel programmer was 80 percent more 
“productive” than the C++ programmer! 

Jony Rosenne 

Tel Aviv, Israel 


Michael responds: Thanks for your com- 
ments, Jony. I believe that you present 
valid arguments when coding with pro- 
cedural languages. But object-oriented 
programming adds a new variable to 
the equation, namely reusability. De- 
signing a class to be reusable takes 
longer than its procedural counterpart. 
The process usually involves an analy- 
sis of the overall design to identify 
components that may be useful in 


10 


more than one context. Such compo- 
nents are likely candidates for abstrac- 
tion. Often, however, this is an itera- 
tive process of designing, coding, 
redesigning, and recoding. Ultimately, 
a full-featured class designed for reuse 
is sure to increase the overall line count. 
The short-term result is that building 
reusable classes takes longer, costs more 
to develop each line of code, and in- 
creases the overall line count. Howev- 
er, the long-term benefit is that the same 
code costs no more to use again. 

The point of my ending comment 
was to raise the reader’s awareness of 
a new problem. Assuming you can 
measure code reuse in the first place, 
is the pain of developing reusable class- 
es worth the gain? And, if you’re ready 
to buy into it, how do you promote 
reuse in your company? More to the 
point, how do you reward the pro- 
grammer for developing reusable code? 


Dear DDJ, 

I was dumbfounded by your inclusion 
of an obscure language such as Drool 
and exclusion of as popular a language 
as Actor from your article in the Octo- 
ber 1993 issue of DDJ. There are over 
30,000 registered users of Actor. It is 
up-to-date with Windows 3.1, and it’s 
commercially available today (Version 
4.0) despite serious disinterest by its 
new owner, Symantec. 

Actor is very much in use and very 
much an issue in Windows-based OO 
development. It was, after all, the first 
OOPL available commercially for Win- 
dows development. It was and is still 
a purely object-oriented language. A 
number of its most vocal enthusiasts 
have begun a constant drumbeat in 
the technical media, which we hope 
will culminate in the language’s sep- 
aration from Symantec and reentry 
into the Windows commercial-devel- 
Opment arena (see my article in the 
August 1993 Windows/DOS Devel- 
oper’s Journal on Actor 4.1). Most of 
Actor’s third-party supporters —Tem- 
pus Software, BOK Technologies, and 
The Windows Wurx— have agreed to 
bundle their Actor add-ons with the 
product at virtually no cost to infuse 
some new life. 

I find it very hard to believe DD/ 
doesn’t keep up on Actor at all but 
manages to keep in touch with the likes 
of Drool, Beta, Sather, and Eiffel. 

Richard L. Warren 

CompuServe 70750,3436 


Dear DD]. 

Your October, 1993 article, “Comparing 
Object-oriented Languages” provided 
just the sort of information that keeps 
me buying DD/. Articles about OOP are 





always of interest to me, and it is re- 
freshing to see languages other than 
C/C++ receive coverage. 

Another object-oriented language 
readers may be interested in is “Mops.” 


Mops is the work of one (very talent- 


ed) individual, Michael Hore of Aus- 
tralia. The language is consistent and 
easy to learn, benefitting from one 
man’s vision. The basic syntax is de- 
rived from a commercial product that 
first appeared in 1984 (Neon), so the 
language is “proven.” 

Example 1 shows a Mops coding ex- 
ample that’s very short because it con- 
veniently already has number (var) and 
point classes that respond in a mean- 
ingful way to a print message (print:). 
Example 1 shows how the point class 
might be defined in Mops. 

Doug Hoffman 

CompuServe 72310,1743 


Dear DDJ, 

I read your October 1993 issue with 
great dismay— here is an issue osten- 
sibly devoted to object-oriented pro- 
gramming languages that does not men- 
tion Oberon-2. I am disturbed because: 
1. Somehow Oberon-2 was not select- 
ed for illustration; and 2. it was not even 
mentioned in the discussion of OOP 
languages. While I understand that 
there are many such languages and 
that in depth coverage of all would 
likely be impossible, I am puzzled 
since some of the languages you did 
see fit to cover probably do not have 
a volume of written code comparable 
to that of Oberon-2. Several excellent 
code examples as well as the Oberon 
operating system illustrate the capa- 
bilities of this well-thought-out evolu- 
tion of structured, modular program- 
ming languages. | 

Also not included was Modula-3. It is 
distressing that in the article, “Compar- 
ing Object-Oriented Languages,” Ada is 
used to provide an approximation of 
the doubly linked list example. Modu- 
la-3 would have been, in my opinion, 
a better choice. In fact, there is an ex- 
cellent set of software components that 
includes the doubly linked list case, 
but also provides iterators and the like 
for accessing and operating on this list 
of possibly heterogeneous node types: 
It is written with Modula-2! (The 
Modula-2 Software Component Li- 
brary, C. Lins, Springer-Verlag.) 

The second matter that concerns me 
is the lexicon that has developed in the 
object-oriented programming arena. I 
have difficulty when simple concepts 
such as type extension and procedure 
variables (and their combinations) be- 
come mired in terminology that largely 
obscures rather than describes or de- 
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New CA-REALIZER 2.0 Beats Visual Basic 3.0, 










Compared to Visual Basic 3.0, 
CA-REALIZER’ 2.0 is half the cost and 
twice the product. 

CA-REALIZER is already 
the easiest, most powerful 
BASIC for Windows and OS/2, 
and with version 2.0 it's even 
better. No one can match our com- 
Y bination of features, ease of use, and 
_ price. No one can make it easier to port 
your applications from QuickBASIC, and 
no one can make it more fun to develop for Windows and OS/2. 

CA-REALIZER also comes with a huge array of powerful, 
plug-and-play tools like spreadsheets, charts, text editors, animation, 
=a] graphics tablets 

a1 and database 
forms, along with 
many features 
other BASICs don't 
offer. Arrays are 
re-dimensioned 
and processed 
automatically. 
Algorithms can 
be written as 
formulae instead 
of complex looped 
expressions. 
Once an applica- 
- tion is complete, 
compile it into a 
stand-alone 
OS/2 or Windows 


CA-REALIZER 


The Complete BASIC 
; agalewen eee System 


cé-Realizer: FormDev - Project: (Untitied) 





mmDev Demo 





application and distribute it royalty-free with the run-time module 
that’s included. And you can generate an installation disk with the 
push of a button. 

PC Computing said, No other 
Windows BASIC can match it for power 
and breadth of features.’ 

At $99, no one can match our price either, and it inthe our 
award-winning Windows report writer absolutely FREE. 


Only CA-REALIZER Gives You All Of This: 


¢ Develop for Windows and OS/2 





ANNUAI 
WIN AWARD 





* Use any standard Windows and OS/2 custom control in FormDev 


¢ Easy migration of QuickBASIC applications to Windows and OS/2 
¢ Interactive WYSIWYG application design 
¢ Full support for DDE and DLLs 


* Dynamically expandable multi-dimensional arrays with a full range of 
array and matrix operators and functions 





Call 1-800-225-5224, Dept. 25302 
Today Or See Your Local Dealer. 





MICROSOFT 





WINDOWS. This offer is ® 
an good for a limited ( OMP UTER 

time only. Call today and find out how a SSOCIATE hy 
much better BASIC can be. Software superior by design. 


New CA-REALIZER 2.0 
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companies. Cost comparison based on Visual Basic Release 3.0 Suggested Retail Price. PC Computing quote appeared 10/91, pg. 90. 


(continued from page 10) 

fines. I will agree that OOP comes into 
its own under large, complex system 
conditions and certainly impacts pro- 
gram design in a fundamental manner, 
but then this is analogous to the effect 
on programming that record, enumera- 
tion and pointer types, and structured- 
programming constructs had at their in- 
troduction. Unfortunately, in the case of 
object-oriented programming languages, 
we are speaking of enhancements to ex- 
isting concepts, principally type exten- 


:class point super{ object } 
sae a 
int v 


a a ee ea 
put: y 
Puts: x 

;m \ end method definition 


‘hi get: (== = 9) 


LETTERS 


sion and broad use of procedure vari- 
ables, rather than the introduction of 
new concepts. Yet these relatively sim- 
ple (and powerful) notions are con- 
founded or lost in the egregious sea of 
OOP-speak. 

Perhaps I must simply give in and rec- 
ognize that we (in the U.S., anyway) are 
living in a “mono-C-istic” programming 
society. I hope, however, that this is not, 
and will not be the case. 

Michael A. McGaw 

Fairview Park, Ohio 


\ begin class definition, superclass is object 
\ declare an instance variable of type integer, named x 
\ declare an instance variable of type integer, named y 


\ begin put: method definition. x, y passed via Forth stack 
\ use put: methods of the int ivars to store values from stack 


\ stuff between parentheses is just a Forth stack picture 


get: x \ x and y will be "gotten" to the Forth stack, ready for any use 


PERSE 3 


print: 
eet: gelt . 
;m 


sclass \ end class definition 


Example 1: Mops code sample. 


. \ finally, we actually use some Forth, the dot (.) to print 





Introducing Track Record’ a new kind of 
tool from the original developers of BRIEF ° 


DDJ responds: Our thanks to the many 
readers who wrote in with similar con- 
cerns about the coverage of so-called 
“obscure” languages like Drool, Beta, 
Sather, and Parasol. Because space con- 
siderations prevent analysis of every 
object-oriented language in a single is- 
sue, the October issue provided a cross- 
section with special attention given to 
nonproprietary languages. In particular, 
Drool and Parasol are in the public do- 
main with complete source code avail- 
able in the DDJ Forum on CompuServe. 


Now On To Forth... 

Dear DDJ, 

Forth is an extensible language but 
Michael Swaine’s example in DD/J 
(November 1993) doesn’t extend Forth 
any more than writing a function ex- 
tends C. Extending a language would 
be like adding the syntax: 


LOOP 
EXIT IF (condition) 


ENDLOOP 


to Fortran or making complex a new el- 
ementary data type in C with exactly the 
(continued on page 16) 


Fix more bugs, 
add more features 
... get more done. 


Developing software means juggling 
hundreds of details. Let just one of 
them fall through the cracks, and 
you're in for headaches. Wouldn’t it 
be great if you had a tool that let you 
take control of all that information? 
Now you do. Track Record™ 
is the first and only application 
designed to help you keep track of 
practically everything relating to your 
work — from bugs to beta sites. It’s a 
whole new kind of productivity tool 
for Microsoft Windows, designed 
specifically for software developers. 


“Indispensable. Track Record definitely 
helped us make LibTools a better product.” 
— Steve Steiner, Integrated Development Corp. 


£ . 


“Track Record is one of the handiest and 
most used tools on my machine.” 


— Mark Edwards, original author of Computer 
Associates CA-ForComment® 





BUG REPORTS 


¢ Track Record lets you quickly and 
easily plan tasks, store and retrieve 
information and keep a detailed 
history of who did what, when. 
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TEST CYCLES 


“An essential development tool. Our entire 
company, from development to marketing 
to support, stays connected with Track 
Record.” 

— Robert Duffy, Director, R&D, Lucid Corp. 


RELEASES ¢ Track Record dynamically displays 


information about your software pro- 
jects as they change, so you're always 
up-to-date. 


SCHEDULES 


DEVELOPERS 
¢ Track Record is ready to use right 


out of the box, or configure it to meet 
your personal needs. Use it individu- 
ally, or on a network to keep your 
entire workgroup on track! 


ORDER NOW FOR JUST $159 
FREE GIFT IF YOU MENTION THIS AD 
Risk-free, 60-day money-back guarantee! 


BETA TESTERS 


DOCUMENTATION 
To order, call UnderWare, Inc. 
today at 800-343-7308 


In MA or outside US, call (617) 267-9743 
or fax (617) 424-1839. 
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Requires Microsoft Windows v3.1 or OS/2 v2.1, 4M total RAM, share.exe or equivalent for network use. 
Track Record is a trademark of UnderWare, Inc. BRIEF is a registered trademark of Borland International. 


UnderWare, Inc., 321 Columbus Avenue, Boston, MA 02116 USA 
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Professional developers today know that portability and 
superior code quality are more than luxuries — they're a AY Un 


matter of survival. Better, faster chips and more robust § P A R C 


operating environments are making their appearance on 
. SunOS ¢ Solaris 1, 2 « CenterLine 
what seems to be a daily basis. MetaWare has a solid Embedded Applications 
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understanding of how these issues affect your business. 
Our 32-bit high-performance multi-platform compilers 
ensure that investments you make with us today will be ® 
safe for you tomorrow. High C/C++ ™ and Professional MetaWare 
Pascal ® are the clear choices for multi-platform software 
development. Call today! 
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Multi-Language, Multi-Platform 
Compiler Products for 
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Q+E Database Library 
by Q+E Software 


Q+E Database Library 2.0 streamlines 
DBMS-independent applications develop- 
ment by providing transparent access to 
major SQL and PC DBMS from user’s 
desktops with automatic support for 
ODBC & IDAPI. QELIB2 works with exist- 
ing development tools and is simply the 
best way to add complete DBMS access to applications today 
and tomorrow! 


List: $699 Ours: $475 FAXcetera #: 2625-0002 


WindowsMAKER 


Professional 5.0 
by Blue Sky Software 


Next generation of the most powerful 
C/C++ Code Generator and Prototyper for 
Windows 3.1, NT & Win32s. The fastest 
way to create full-featured Windows apps. 
This product stands out, does every- 
thing—even a toolbar can be created with 
1 click! Test run your design, make changes interactively, gen- 
erate code for multiple platforms—ANSI C, MFC, OWL, etc.; 
widest compiler support in industry. TrueCode technology— 
user code is 100% preserved. Highly recommended! 


List: $1096 Ours: $875 #FAXcetera #: 2602-0003 





c-tree Plus® 
by FairCom 


DOS * WINDOWS © NT « UNIX * OS2 * SUN gS 


© RS6000 * HP9000 * MAC « ONX e 

BANYAN ¢ SCO. This well known, highly 

portable data management package has 2: 
become established as the tool of choice for FAIRCOM? 
commercial development. Offering unprece- since 1979 
dented data control, programmers may 

choose from direct low level access, ISAM level convenience, or 
SQL access with the FairCom Server. Single User, MultiUser, or 
Client/Server, ANSI Standard. 


List: $595 Ours: $505 FAXcetera #: 1381-0008 
Call Programmer's Paradise® Italia for special pricing in Europe. 





o * "~*~ Network C Library 
by Automation Software 
Consultants, Inc. 


The most comprehensive library available 
for NetWare software development, support- 
ing all versions of advanced NetWare. Over 
- ee “2 450 C functions, include any features from 
ty By. Be. Fy the NetWare command line utilities and 
Asc1 menu utilities in your C or BASIC programs 
for Windows or DOS. No licensing hassles. 
C library source code available. 


List: $395 Ours: $355 FAX cetera #: 1004-9201 
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IntegrAda for Windows 
by Aetech Inc. 


A complete Ada Programming Support 
Environment (APSE) for Windows, adding 
a language sensitive editor; automatic code 
generation & error checking; interactive 
error correction; pop-up menus to com- 
pletely customize the environment to the a aereon 
standard Windows features. Allows you to ae 
quickly code, correct, compile, and link 

your Windows programs using Ada. Includes environment, 
libraries, validated Ada compiler, Ada Windows Libraries, 
Header Files, Resource and Help compilers, and Microsoft 
Linker. (ACVC 1.11 validation pending) No Runtime Royalties! 


List: $995 Ours: $895 FAXcetera #: 2358-0003 
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WATCOM VXeRExx 
by WATCOM Int'l Corp. 


WATCOM VX*Rexx is an easy to use visual 
development environment for creating 
applications that leverage the capabilities of 
OS/2 2.x and exploit the Presentation 
Manager graphical user interface. VX*RExx 
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combines a project management facility, 
visual designer and an interactive source- 
level debugger to deliver a very approachable and highly pro- 
ductive visual development environment. 


List: $199 Ours: $99* FAX cetera #: 1683-0016 
*Pricing valid while supplies last. 
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MetaWare .. ~+=MetaWare High C/C++ 


by MetaWare, Inc. 


NEW RELEASE! High C/C++ version 3.1, 
MetaWare’s 32-bit compiler, is shipping. 
Includes a 32-bit source-level debugger, 
and a 32-bit Application Developer's , | 
Kit for Windows. The “Incremental ~ 
Strengths” feature enables gradual 
migration from C to C++ one block at a time. High C/C++ pro- 
vides optional ANSI conformance, eight levels of global optimiza- 
tion and a full implementation of C++ templates. 


List: $795 Ours: $669 FAX cetera #: 1590-0008 
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TURN TO TURNING POINT 


For a very simple reason - We under- 
stand the business of software product 
development and we’ve been doing it 
successfully since 1983. 

Our approach to project management 
insures proper controls, scheduling and 
budgeting. With a full time Quality 
Assurance and experienced Software 
Engineering staff, we have the technical 
excellence and proven track record to 
get your product done right. Plus, our 
experience in Macintosh®, 

MS-Windows® and DOS cross platform 
development is unparalleled. 

Turning Point Software, the one to 
turn to for software product development 
at its best. 

Call or write for a free portfolio. 


BES) Turning Point 
software 
One Gateway Center 


Newton, Massachusetts 02158 
617-332-0202 


CIRCLE NO. 609 ON READER SERVICE CARD 
16 





a as - come ie" the word into the aiettonary | 


(continued from page 12) 
same standing as int— reserved word 
and all. 

The syntax of Forth is extremely sim- 
ple: “Words” are character strings de- 
limited by whitespace. The semantics 
of Forth are simple, too; nearly all 
words are imperative verbs: 


e Some few “defining” words add words 
to the dictionary, so the first time a 
user-defined word appears, the defin- 
ing word puts it in the dictionary. 

e Thereafter, the newly defined word is 
an imperative verb. 

e A few “immediate” words are exe- 
cuted during compilation. 

e Most words are not executed during 
compilation— they are “compiled” 
into the dictionary during compilation. 


Because of these two simplicities, the 
Forth compiler can be exposed to the 
programmer. (The source code for the 
fig-Forth text interpreter, compiler, and 
keyboard debugger fits on a screen of 
16 lines of 64 characters with plenty of 
whitespace.) Extending Forth consists 
of defining: 1. new immediate words 
which have a compile-time effect, and 
2. new defining words. 

A truly marvelous feature of Forth al- 
lows the programmer to specify the 
compile-time effect of new defining 
words and the run-time effect of words 
defined by the new defining word. The 
corresponding chore in, for example, C 
would require: 


¢ Defining the new syntax so that it isn’t 
ambiguous and doesn’t conflict with 
existing syntax (nontrivial). 

e Defining the semantics of the new 
syntax (pretty easy). 

e Altering the parser and diagnostics 
of the compiler to recognize and di- 
agnose the new syntax (without im- 
pact on parsing or diagnosing old 
syntax!). 

e Altering the code generator so that the 
new target code implements the new 
semantics (without impacting such 
things as register usage, optimizers, 
and so forth). 


The fig-Forth text interpreter, key- 
board debugger and compiler looks 
something like Example 2. While some 
programmers are attracted to Forth by 
its simplicity and compactness, others 
are attracted by extensibility. Some of 
the first object-oriented languages I 
ever saw were implemented by exten- 
sion of Forth. 

William E. Drissel 

Grand Prairie, Texas 
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The DDR compiler—a tool for 
binary-file portability 





José Luu 


ooner or later, all developers writing cross-platform appli- 
cations to run on 80x86/Windows and RISC/UNIX plat- 
forms have to grapple with binary-file portability. Binary 
files saved by a PC usually have a data representation 
natural to the 80x86 architecture. If the application program 
is ported to the UNIX environment, the data representations 
in the new system are likely to have a different byte order, 
alignment, and size. To minimize programming efforts, you 
want the file read/write routines to work in both 80x86 and 
RISC environments and produce compatible data files, all 
without an elaborate rewrite of the source code. 
Programmers choose to write binary data because it’s easy. 
Usually, the format of the binary file is the same as the data 
image stored in memory. The code necessary to write binary 
data to a file is often as simple as a few instructions. There is 
no need to convert the data into some complex format. The 
raw data is just sent to the disk. It is simple, fast, and concise, 
but it also tends to be nonportable. One of the most popular 
forms of binary data, for instance, is the binary graphic image 
(bitmap). The graphic image consists of a header structure in- 
dicating how the data is arranged, followed by the data itself. 
With MainWin for Workstations, a tool that provides the 
Windows API on UNIX workstations, one of our goals was 
to create a truly portable way to handle the differences in 
binary-data representation in all environments, while retain- 
ing a single source-code base and without having to manu- 
ally add a lot of elaborate data-translation code. We knew 
programmers cross-developing PC-based Windows applica- 
tions to run on these workstations would often need to deal 
with binary-file portability. 


José is vice president of engineering at Mainsoft Corp. He can 
be reached via Internet mail at jluu@mainsoft.com. 
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Our solution to the binary-data conundrum was to create 
an underlying technology we call “DDR compiler.” While DDR 
is short for “DOS data representation,” it could more precisely 
be referred to as the “Intel 16-bit data representation.” 

Our scheme works best when programmers simply write 
the contents of a structure to disk; see Example 1. Using 
DDR-based tools, you can automatically generate file read/ 
write macros that handle the differences in binary-data for- 
mats between the 80x86 and a number of RISC workstation 
platforms (IBM RS/6000, HP700, Sun, SGI, and the like). You 
can also extend the tool to translate the data representation 
to or from practically any architecture. This is because the 
tool is built from a simple script that uses a common UNIX 
network utility found on most workstations, rpcgen. 

The DDR compiler takes for its input the data typedefs and 
structures from your application’s header files. Its output is 
a new header file and a C source file that implements cus- 
tom read/write functions. This file can be easily incorporated 
into the application, making binary data available across all 
supported platforms. Because the new read/write macros are 
conditionally defined, they’re expanded back into their orig- 
inal forms when compiled on the PC, allowing a single code 
base to be used for both the PC and RISC platforms. 

This article details the basic DDR architecture. The com- 
plete source code for the DDR compiler described here is 
available free of charge at ftp.mainsoft.com. Although Main- 
soft retains all rights to the source code, you can download 
a copy, modify it, use it for your own purposes (commercial 
or otherwise), and include the object code in your library. 
We do ask that you don’t upload the software to a BBS or 
pass it along to others. 


Sharing Binary Data Between Systems is Not New 

Of course, movement of data between systems with differ- 
ent data representations isn’t new. It has been a perennial 
problem, and there are many schemes for managing such 
operations. The one we employed is based on that used by 
the Sun Remote Procedure Call (RPC) protocol. 

The idea behind RPC is to allow programs to easily access 
compute resources across a network. A program running in 
one machine makes a call to a procedure in another ma- 
chine. To make this work, a scheme had to be devised to 
standardize the data representations of the procedures’ calling 
arguments and the results. To execute a procedure in another 
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system, calling parameters are converted to a binary neutral 
format understood by the other system. The return values 
from the call are also provided in the binary neutral format. 
Each system provides the logic to translate data to and from 
the common binary format. This process, which is illustrated 
in Figure 1, is referred to as “data marshaling.” There are a 
number of formats of this kind, each corresponding to a given 
protocol, including Courier data representation of the Xerox 
Network Protocol, Sun’s XDR, and the X409 ISO standard. 

To accomplish data translation to and from the standard 
neutral format, you have to write the necessary translation 
routines. Inventors of these protocols were quick to realize 
that this was a mechanical task that could easily be auto- 
mated. That’s how they came up with structure compilers 
that would write the translation procedures for them. The 
most widely available compiler is the rpcgen tool, so we 
chose it to develop the DDR compiler. Rpcgen is the struc- 
ture compiler used for developing RPC procedures compli- 
ant to the Sun RPC protocol, so it is potentially available on 
many platforms. 

Rpcgen’s basic functionality is exactly what’s needed to 
translate the 80x86’s common data format into a form usable 
on RISC workstations. Rpcgen generates the high-level trans- 
lation routines for the complex structures. However, nothing 
within rpcgen’s domain allows for direct translation between 
particular data representations. For that, we developed our 
own low-level DOS/UNIX translation library routines. Figure 
2 illustrates how we use rpcgen for DDR functionality. 


How DDR Works 

The DDR tool consists of the ddrgen program and associat- 
ed library and header files. Ddrgen is simply a script that 
wraps around a call to rpcgen and subsequently modifies the 
files generated by rpcgen so that calls are made to the ddr 
library instead of the xdr library. 

Ddrgen takes as input the structure definition of the binary 
data, defined with approximately the same syntax as a C 
header file. I say “approximately” because the ddrgen syn- 
taxer (the rpcgen syntaxer) does not allow complex struc- 
ture declarations. 

You might need to simplify some of the data-structure def- 
initions. For instance, the rpcgen front end does not sup- 
port the declaration of nested structures. In such situations, 
the nested structure can be declared at the top level and its 
name used inside other structures in order to achieve the 
same results. 

The structure definitions drive ddrgen. As a result, ddrgen 
outputs three files that can be incorporated into your appli- 
cation source code: 


e filename_ddr.c, a C source file containing the read and 
write translation routines constructed from the input-file 
data definitions. 

e filename_ddr.h, a header file for filename_ddt.c. 

° filename_rw.h, a header file that must be inserted into all 
application source modules that read or write binary data 
using the DDR scheme. 


The C source file which acts as a data translator is made 
up of a series of simple function calls, one for each data el- 
ement in the structure definition that drove the process. For 
instance, your input structure might look like Example 2(a), 
where struct is a typedef that has been defined before. 

The DDR compiler outputs a C file with the ddr_MY- 
STRUCTURE function call, which contains a series of func- 
tion calls that encode or decode each data element. Since 
the input structure contains three data elements, the result- 
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BINARY DATA 


ing function has three translation calls, arranged in the same 
order as the structure definition. Thus, the output file would 
look like Example 2(b). 

Ddrgen creates the translation calls by constructing the func- 
tion-call names from the data types called out in the input 
structure definition. The low-level functions for integers, shorts, 


struct MYSTRUCTURE { 
int mydatal; 
strucil mydata2; 


long mydata3; 
} mydata; 


nStatus = fwrite (&mydata, sizeof (MYSTRUCTURE), 1, stream); 


Example 1: Writing contents of a structure to disk. 





Figure 2: The use of rpcgen simplifies the translation process. 


(a) struct MYSTRUCTURE { 
int mydata1; 
strucil mydata2; 
long mydata3; 


(b) bool_t ddr_MYSTRUCTURE (ddrs, objp) 
DDR *ddrs; 
MYSTRUCTURE *objp; 
{ 
if (!ddr_int(ddrs,objp->mydata1)) return (FALSE): 


if (!ddr_struc1(ddrs,objp->mydata2)) return (FALSE) ; 
if (!ddr_long(ddrs,objp->mydata3)) return (FALSE) : 
return (TRUE); 


Example 2: (a) A typical input structure; (b) C code 
generated by the DDR compiler. 


nStatus = write (fd, &mydata, sizeof (mydata)); 

ddr_write (fd, mydata, sizeof(mydata), MYSTRUCTURE, &nStatus); 

nStatus = fwrite (&mydata, sizeof(mydata), 1, stream); 

ddr_fwrite (&mydata, sizeof(mydata), 1, stream, MYSTRUCTURE, &nStatus) ; 


nStatus = read (fd, &mydata, sizeof(mydata)); 
ddr_read (fd, &mydata, sizeof(mydata), MYSTRUCTURE, &nStatus); 


nStatus = fread (&mydata, sizeof(mydata), 1, 


stream); 


ddr_fread (&mydata, sizeof(mydata), 1, stream, MYSTRUCTURE, &nStatus) ; 


Example 3: Standard read and write routines compared 
to DDR equivalents. 





Figure 3: DDR system block diagram. 
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and the like are provided in the translation library. To call the 
ddrgen- generated functions, you replace your binary file fread 
and fwrite function calls with new DDR calls that know about 
the translation code. (This assumes that the program is written 
in the way I described earlier, simply reading and writing data 
structures directly to a file. If the program does otherwise, 
some code would have to be rewritten to employ this scheme.) 
Four new macros replace the standard functions. 


¢ ddr_write replaces write. 
¢ ddr_fwrite replaces fwrite. 
¢ ddr_read replaces read. 
e ddr_fread replaces fread. 


The process of replacing the read and write routines with 
their DDR-equivalents is not much more than a simple search- 
and-replace process with your editor. You also have to tell 
each DDR routine which data structure to read or write. Ex- 
ample 3 shows read and write routines compared to their 
DDR equivalents. You can see that the functions are similar, 
but there are two additional parameters to pass, MYSTRUC- 
TURE and nStatus. The DDR system block diagram (Figure 
3) shows how the various elements of the application are 
linked to form an executable. 

To see how all the elements of the DDR system work to- 
gether, I'll examine how a single data translation takes place, 
starting at a ddr_ fread function call and tracing the process 
all the way through. I’ll assume that you ran the DDR com- 
piler and did the edits to your source files. 

The ddr.h file, which is included by filename_ddr.c, con- 
tains many of the core definitions of the DDR system, in- 
cluding the conditional statements (#ifdefs) that select be- 
tween the PC-compatible read/write routines and the new 
translation routines. The code is set up so that if it is com- 
piled in a PC environment, the original fread and fwrite rou- 
tines are used. If compiled for a supported RISC machine, 
the DDR routines are used. In this example, assume that I’m 
cross- developing to a 32-bit RISC machine. 

In this case, the ddr_fread macro is expanded, as in Ex- 
ample 4(a). ddr_fread creates a DDR handle (ddrs) using 
the ddrstdio_create function. ddrstdio_create will initialize 
the ddr handle for reading from the file stream and set up 
compatible data-translation function calls in the DDR struc- 
ture. In addition, it knows this will be a DDR_DECODE Op- 
eration, and it stores the DDR_DECODE operation code in 
the DDR handle to use later to select a read routine. 

The next line constructs a call to the user’s structure- 
translation function. In the example, the user’s structure is 
called MYSTRUCTURE; this parameter is substituted for 
##Name to produce Example 4(b). 





DDR Translation 
oe brary | 
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Cross Development Support 


C/C++" supports a wide range of 32-bit Intel x86 host and target platforms 
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development capabilities of today’s operating environments including 
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(continued from page 20) 

Recall that this function was created by ddrgen (in the file- 
name_ddr.c). It sequentially executes a translation of each 
element in the structure. For this example, focus on just the 
first element since they all act approximately the same; see 
Example 4(c). 

The function ddr_int in Example 4(c) is a call to the DDR 
int translation function. (The function ddr_struc/ is a call to 
a function that has also been constructed by the ddr com- 
piler when it has processed the previously defined struc1. 
This is how we handle nested data structures.) 

The translation functions are constructed using a few prim- 
itives keyed to the 80x86 architecture: Read routines read 


(a) ddr_fread vee nSize, nNumber , stream, Name, pnStatus) { 
DDR ddrs 
ddretdic. create (&ddrs, stream, DDR_DECODE); 
if (ddr_##Name(&ddrs, (voiay) (opera ee 
*(pnStatus) = ddrs. nCount ; 
else *pnStatus = -1; 
ddrstdio_destroy (&ddrs) ; 


/* tl ae ee. when done */ 


; | 
(b) if (ddr_MYSTRUCTURE(&ddrs, (void) (pData))) ... 


(c) bool_t ddr_MYSTRUCTURE (ddrs, ae 
DDR *ddrs; 
MYSTRUCTURE *objp; 
{ 
if (!ddr_int(ddrs, objp- sapdete) return “(panse): 
if (!ddr_struci(ddrs, objp->mydata1)) return (FALSE) ; 
/* eta... */ 
return (TRUE) ; 


Example 4: The expanded ddr_fread macro; 

(b) substituting MYSTRUCTURE for ##Name; (c) the 
ddr_MYSTRUCTURE routine sequentially translates each 
structure element. 





80x86 data, and write routines write 80x86 data. These prim- 
itives include read/write routines for byte (8-bits), short (16- 
bits), and Jong (32-bits). 

ddr_int uses the DDR_DECODE opcode to select the 
DDR_GETSHORT macro. Example 5(a) shows the code that 
does it in ddr.c. ddr_int creates a short storage space (sValue) 
to receive the int from the selected macro. Notice that if the 
opcode was DDR_ENCODE, the DDR_PUTSHORT routine 
would have been selected. DDR_GETSHORT is a macro that 
expands Example 5(b). The macro DDR_GETSHORT is ex- 
panded to a call to the function stored in the getshort field 
of the operations_vector of ddrs. 

Recall that I chose to use ddr_fread for example, and that 
the macro expanded to open our DDR handle with the func- 
tion call ddrstdio_create(). As a part of its process, ddrstdio 
initialized ddrs->operations_vector to a whole list of low-lev- 


short sValue; 
switch (4drs->operation) { 
case DDR_ENCODE: 
return (DDR. aoa 
case DDR_ DECODE: 
*ip = @; 


© bool_t ddr_ int (DDR * drs, int “#ip) a 


C\eiott #) ip)3): 


/* oo whole int because the reading will 
only affect the lower part */ 
if (!DDR_GETSHORT(ddrs, &sValue)) { 


return (FALSE) ; 


*ip = sValue; A this is how the translated int is passed 
back up */ 
return (TRUE) ; 


(») #define DDR_GETSHORT (ddrs, ane) \ 
(# (drs) - >operations_vector->getshort) (ddrs, _shortp) 





Example 5: (a) The ddr_int routine uses the 
DDkR_DECODE opcode to select the DDR._GETSHORT 
macro; (b) the DDR_GETSHORT macro. 
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Windows® or IBM’s OS/2 PM.° . 


Flexibility And = & 
Functionality. 


The ideal combination of flexibility and func- 
eer tionality has made SA the undisputed 
ee price/performance leader. As the needs 
an of developers have changed, so has the 
WINDOWS. scope of SA’s features and options: 

SA Screen Painter: Allows repository- 
based development of GUI screens and menus 
or character-based screens. 

SA Object-Oriented Version: 
Booch ‘91 and Coad/Yourdon. 

SA Reverse Data Engineer: Reverse engi- 
neers SQL databases, including SQL Server, 
SYBASE, DB2, Informix, and Oracle. 

SA Schema Generator: Generates DDL 
and SQL triggers from entity models for 
Oracle, Informix, Ingres, PROGRESS, 
Paradox, dBASE II, DB2, SQL Server, 
SYBASE, and other SQL and 4GL databases. 

SA Project Documentation Facility: 
Enables the automatic generation of 

: deliverables 
with desk- 
top publish- 
ing quality 
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Choose Your Development 
Environment. 
SA/PowerBuilder Link: Allows the 


exchange of design information between SA 
and PowerBuilder for the development of 
more robust client/server applications. 

SAISQL Windows Link: Works with 
Gupta’s SQL Windows. 
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REQUIREMENTS ANALYSIS DESIGN | CONSTRUCTION 


System Architect 3.0 covers your development lifecycle 
with a complete range es ‘features and options. 


Put Your Project Team In 
A Class Of Its Own. 


client/server applications. ‘That's 
why I developed System Architect 3.0.” 


JAN POPKIN, CHIEF SCIENTIST 
POPKIN SOFTWARE & SYSTEMS, INC. 


sharing the SA Repository by locking diagram 
and data dictionary records. 

Network Security: Allows Project Managers 
to uniquely identify and classify personnel with 
appropriate levels of authorization. 

Access Control: Allows team members to 
check-out, check-in, or freeze encyclopedia 
objects with defined authorization. 

Version Control: Allows project encyclope- 
dias, and their related files, to be saved and stored 
with appropriate version-identifying data. 
(Available in version 3.1) 


Call Us Today At 
800-REAL-CASE, X131. 


To find out how to qualify for your free 
30-day evaluation copy, call us today, or fax 


us at 212-571-3436. 
SYS TEM A 
Popkin Software & Systems, Inc., | 


ARCHITECT 
11 Park Place, New York, NY 10007 





from SA _ System Architect 3.0 makes your project team England 44-926-881186; Benelux 31-3406-65530; 
Encyclopedia. more productive with a range of capabilities Germany 49-6151-82077; Italy 39-49-8700366; 
<PaintGUI __ including: Switzerland 41-61-6922666; Denmark 45-45-823200; 
phir from Network Version: Allows multiple team mem- Australia 61-02-346499; Sweden 46-8-626-8100; 
repository. bers to work concurrently on a project while Elsewhere 1-212-571-3434 

© 1994 Popkin Software & Systems, Inc, The System Architect logo is a trademark of Popkin Software & Systems, Inc. All other brand and product names are trademarks or registered trademarks of their respective holders. 
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BINARY DATA 
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(a) boo_t ddrstdio_getshort(DDR * ddrs, short *sp) { 
short sBuffer; 
if (fread((caddr_t) & sBuffer, sizeof(short), 1, (FILE *) 
ddrs->ddr_private) != 1) 
return (FALSE); /* If you cant get the int, return a fail 
code */ 
MoveShort (&sBuffer, sp); 
ddrs->nCount += sizeof(short); 
return (TRUE); 
} 


(b) #define MoveShort(pSrc,pDest) (*(char*) (pDest) = \ 
*((char *) (pSre)+1), \ 
*((char*) (pDest)+1) = *(char *) (pSrc)) 





Example 6: (a) Fetching the next int from the input 
stream and does the conversion, storing the result in the 
target structure, (b) the MoveShort macro. 


(continued from page 22) 

el function calls designed specifically for the fread transla- 
tion. This gives the flexibility to have other getshort opera- 
tions read data from different sources. For instance, creating 
the DDR handle with ddrmem_create would allow translat- 
ing data to or from a memory buffer instead of a file. 

You can see in Listing One (page 88) that operations_vector 
-> getshort is a pointer to a function. It was initialized by the 
create function to call ddrstdio_getshort. This routine fetch- 
es the next int from the input stream and does the conver- 
sion, storing the result in the target structure. Example 6(a) 
shows this step. 

The routine first freads the next short into a little 2-byte 
buffer, sBuffer. (Notice that this is the fread that you replaced 
with the ddr_fread macro. The DDR compiler has built all 
this superstructure above it and a little code below it also.) 

Finally, MoveShort is called; see Listing Two (page 88). 
MoveShort has been selected by #ifdef architecture to be the 
translation macro for the selected target architecture. For this 
example, I’m assuming a Sparc or other Big-endian RISC ma- 
chine. The actual byte-by-byte translation now takes place; 
see Example 6(b). (This implementation happens to be a 
macro, but it could also be implemented as a function.) This 
little gem takes bytes from pSrc (source) and stores them in 
pDest (destination), swapping the two bytes, as required by 
the RISC machine. pDest points to the short sValue allocated 
in the ddr_int routine. ddr_int will eventually get control 
back and put the short translated value (sValue) at the loca- 
tion pointed by ip (an integer pointer—4 bytes) in the 
application data structure. This implements the 2- to 4-byte 
extension required for integers. 

To recapitulate, I substituted ddr_fread for fread. 1 then 
went from ddr_fread to ddrstdio_create and ddr_MYSTRUC- 
TURE. | then chose to follow the first ddr translation, an int, 
which took us to ddr_int, and then to DDR_GETSHORT. 
DDR_GETSHORT expanded to ddrs->operations_vector>get- 
short in the DDR structure, which was initialized earlier (by 
ddrstdio_create) to ddrstdio_getshort. It read a 2-byte element 
from the input stream, translated it with a version of MoveShort 
(selected by an #ifdef architecture), and returned. 


Conclusion 

For all its complication internally, the DDR compiler turns 
out to be simple to use. It is a very useful tool for creating 
platform-independent read/write routines for binary data. 
The overall scheme is here. If you want to investigate it fur- 
ther, you can download the complete DDR compiler source 
code via ftp at /tp.mainsoft.com. 


DDJ 


(Listings begin on page 88.) 


To vote for your favorite article, circle inquiry no. 1. 
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C/S ELEMENTS is a true object-oriented develop- Zz 
ment environment that supports polymorphism, 
inheritance, encapsulation, classing and 
sub-classing. 


Introducing C/S Elements 


The next generation client/server development environment. 


Moving to a client/server environment calls for robust tools that management and file I/O. C/S ELEMENTS. All the elements you 
deliver power, productivity, portability and flexibility to your need to succeed in client/server development. 
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system that delivers mission-critical, database-independent 
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language. A rich, object-oriented C/C++ interface. And a complete 
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The WRAPI Toolkit 





A multilanguage toolkit 
for C libraries 





Gregory C. Saratin 


ike many software developers, I 

program in multiple languages. In 

addition to C/C++, I regularly use 

Visual Basic, Clipper, FoxPro, and 
Paradox. After many years of devel- 
opment, my office shelves began to 
sag under the accumulated weight of 
third-party support libraries. At last 
count, I had four communications li- 
braries (one each for Clipper, FoxPro, 
C, and Visual Basic), multiple printing 
tools, and a variety of other libraries. 
After reflecting on the time it takes to 
learn and remember four or five ways 
of accomplishing the same thing, I de- 
cided to create a language-independent 
API that generates language-specific 


libraries. I call it WRAPI, short for B 


“wrapped API.” 

By inserting a translation layer be- 
tween the host-language API and the 
internal functions of a library, WRAPI 
creates a higher-level access to what 
has typically been the domain of C and 
ASM programmers. A C library written 
with the WRAPI toolkit will find a 
much wider audience than a C-only li- 
brary. The number of non-C develop- 
ers, particularly in the high-level lan- 
guages, is growing dramatically, and 
WRAPI provides a way to leverage 
costly development efforts into this 
large market. 

The host languages WRAPI supports 
include C, Clipper, FoxPro (DOS and 


Greg is a consultant and multilanguage 
developer. He is also the author of the 
In-Press tool marketed by Dabiwa. He 
can be contacted on CompuServe at 
73747, 3112. 
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Windows), Visual Basic (DOS and Win- 
dows), Pascal, Clarion, Fortran, and 
many Windows tools via a generic DLL. 
Certain types of libraries lend themselves 
to WRAPI. Anything that is currently 
called an API (such as Microsoft’s Mail 
API or the ODBC API) is a candidate 
for WRAPI. WRAPI can also be used 
with universal functions such as math- 
ematics, communications, printing, and 
multimedia. 

WRAPI is proven technology. It’s cur- 
rently the core technology in Dabiwa’s 
In-Press tool, which provides a set of 





functions for developers who need to 
produce published- quality output from 
within host applications. Because In- 
Press is built from WRAPI, it works with 
all of the major development languages 
on the PC platform. With this article, I’m 
putting WRAPI technology into the pub- 
lic domain, making the source code 
available electronically through DDj. see 
“Availability,” page 3. 


WRAPI Defined 

You usually don’t talk in terms of an 
API when writing a C function library. 
Such functions are compiled into a LIB 
and subsequently integrated into an ex- 
ecutable whole by a linker. As long as 
symbol-naming and parameter- passing 


conventions are uniform among the var- 
ious components, the executable will 
indeed execute. 

Instead, the term API is generally as- 
sociated with the high-level languages. 
FoxPro provides API functions for ev- 
erything from memory allocation to low- 
level I/O. Clipper provides API func- 
tions for parameter passing. Visual Basic 
for DOS requires that strings be deref- 
erenced with StringAdress(), arguably 
an API function. 

The term API in the context of 
WRAPI stands for the interface layer of 
the host language. In C, that layer is 
simply the call stack and the C standard 
library. In reality, there is no API. For 
the purposes of WRAPI, the term “API” 


| isa fiction of convenience. Throughout 
| the rest of this article, I’ll refer to the 


host API when I wish to reference the 
interface layer of the target develop- 
ment language. 

I use the term “wrap” because WRAPI 
resolves differences by “wrapping” them 
in a macro or a data structure. WRAPI 
provides a mechanism for hiding the 
various methods of parameter passing 
that exist among the supported host 
APIs. It also provides uniform mecha- 
nisms for error handling, string manip- 
ulation, memory allocation, low-level 
I/O, and printing. It accomplishes this 
through a combination of preprocess- 
ing tricks and a set of support functions 
which I'll call the “WRAPI library.” 

Incidentally, the first wrapping func- 
tions I wrote were patterned after the 
original work of Dabiwa’s David Kara- 
sek, who used compiler directives 
(4IFDEF, #ELIF, and so on) and boiler- 
plate code to write functions that con- 
ditionally compiled to C, Clipper, Fox- 
Pro, and Visual Basic. Dave’s work 
provided a good starting place to fur- 
ther the concepts of multilanguage sup- 
port. In working with his functions, I 
realized that most of the compiler di- 
rectives were required to resolve dif- 
ferences in parameter passing, so that 
is where I began my attack. 
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(continued from page 20) 
Wrapping Functions 
The first task in developing WRAPI was 
to create the specification for “wrap- 
ping” functions— a translation layer that 
sits between the host API and the un- 
derlying “core” function; see Figure 1. 
A wrapping function grabs param- 
eters from the host API, type-checks 
them (for weakly typed languages), 
calls the core function, traps any er- 
ror condition, and returns a value to 
the host API. All serious work is han- 
dled by the core function, including 
the task of domain checking parame- 
ters. In the initial iteration of WRAPI, 
I made the mistake of putting all pa- 
rameter checking in the wrapping 
function. It seemed logical at the time, 
but I subsequently learned that wrap- 
per functions work best when they’re 
free of semantic content. 
Traditionally, parameters and return 
values are placed on the call stack. 
FoxPro and Clipper don’t pass param- 
eters in this manner. Xbase is a weak- 





Fig : 
API and underlying core function. 











ly typed language, and the mechanisms 
for passing parameters are structured 
accordingly. Clipper provides a set of 
API functions to grab parameters off 
of the Clipper “Eval” Stack (an inter- 
nally maintained Clipper stack). Fox- 
Pro passes a pointer to a structure 
which itself points to an array of struc- 
tures, each of which contains a pa- 
rameter reference. Both Clipper and 
FoxPro include a set of functions for 
returning values through the host API. 
Listing One (page 89) illustrates the 
differences among C, Clipper, and Fox- 
Pro parameter passing. 

Encapsulating the Xbase parameter 
mechanisms was straightforward. The 
WRAPI library includes a set of func- 
tions for grabbing and type checking 
Clipper and FoxPro parameters. The 
trick was reconciling the call-stack 
method of parameter passing with the 
explicit parameter grabbing of the Xbase 
languages. After some fiddling, I came 
up with the function template in Ex- 
ample 1, which works uniformly well 
for both. 

All uppercase keywords are WRAPI 
macro definitions. Many, such as TYPE_?, 
are keyed to a basic data type. WRAPI 
supports six such data types: C, char; S, 
string; B, Boolean; I, short int; L, long 
int; and D, double float. 

Thus the macro TYPE_I indicates that 
the wrapping function returns a short 





The WSTR data structure handles all variations of strings. 


Example 1: The “wrapping” function template. 





Table 1: WSTR functions. 
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integer, while the macro GRAB_S() 
grabs a string-type parameter from the 
API. Listing Two (page 89) is a simple 
wrapping function written with WRAPI 
macros. The function has been stripped 
of the error-handling mechanisms so 
that you can better understand the ba- 
sics of parameter wrapping. The corre- 
sponding translations to the C, Clipper, 
and FoxPro APIs are illustrated in List- 
ing Three (page 89). 

The form of the wrapping function 
may seem a little bizarre at first, but it 
is a bit of preprocessing trickery that 
greatly increases code readability. 


String Handling 

After reconciling the different parameter- 
passing conventions, the next step was 
to deal with strings. In C, we generally 
work with zstrings (short for “zero- 
terminated strings”). Many of the host 
languages, including Visual Basic for 
DOS, FoxPro, Clarion, and Pascal, pass 
buffered strings of one type or another. 
My first inclination was to convert all 
strings to zstrings at the wrapping- 
function level. 

This approach would have allowed 
core functions to work exclusively with 
zstrings, the advantages of which are ob- 
vious. The strategy was simple enough: 
Allocate a chunk of memory one byte 
longer than the buffered string, copy the 
buffered string, and zero terminate it. 
But some APIs provide precious little 
available heap, so a function that re- 
ceives a 48K string would have to burn 
up another 48K of heap space simply to 
add a zero terminator. 

The alternative was a data structure 
that could handle the various string 
types with equal aplomb. This structure, 
the WSTR, is shown in Figure 2. The 
PREP_SQ() and GRAB _S() macros auto- 
matically create and load a WSTR struc- 
ture with the necessary components of 
the API string. All API strings are re- 
solved to an address stored in the cp 
component and a string length stored 
in the wien component. Some APIs 
pass strings via a handle. In such cases, 
the handle is stored in the u/Hnd com- 
ponent. 

The WSTR approach adds a level of 
complexity to writing core functions. 
Most would agree that it is easier to 
work with zstrings than a buffered hy- 
brid such as WSTR. Unfortunately, the 
wrapping macros worked much more 
efficiently using the WSTR, and that 
tipped the balance. Listing Four (page 
89) shows a simple string-manipulation 
function. The associated C, Clipper, and 
FoxPro translations are shown in List- 
ing Five (page 89). These translations 
are quite involved and are beyond the 
scope of this article. 
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Smoothly. Easily. That’s the 
beauty of POET, the Object- 
Oriented Database System for 
C++. It’s simply a more effi- 
cient way to work, and yields 
finished applications that 
outperform relational applica- 
tions in both productivity and performance. 

What’s the secret of Object Oriented Database 
programming? The POET ODBMS works with a one- 
step approach, seamlessly integrating into your appli- 
cation by storing your C++ objects in the database. By 
contrast, the relational approach forces you to design 
and maintain separate application and database mod- 
els and then write lots of code to tie them together. 

So POET is more direct. More logical. And far more 
productive. 
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For a limited time, 
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POET Personal Edition 2.1 for Windows for just 
$299". Or, call toll free to request a revealing white 
paper that compares the two methodologies and 
includes testimonials from key POET installed 
clients. You’ll find that POET is the solution to your 
application design puzzles. 


Call 1-800-950-8845 
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*This introductory offer is good through March 31, 1994. ¢POET applications are portable, at source and database level across all these popular platforms: 
Windows, OS/2, Macintosh, Windows NT, UNIX (Sun, Silicon Graphics, IBM), NEXTSTEP 486 and Novell (NLM) 
POET Software Co. 4633 Old Ironsides Dr., Suite 110, Santa Clara, CA 95054 TEL: (408) 970-4640 FAX: (408) 970-4630 
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(continued from page 28) 

Once I decided to wrap strings in a 
WSTR structure, it became necessary to 
write a set of manipulation functions. 
The WRAPI library provides a basic set 
of WSTR functions; see Table 1. 


The C Standard Library 

String manipulation highlights one of 
the bigger drawbacks of WRAPI de- 
velopment. There are effectively no C 
standard-library functions. Staples of 
the C programmer such as strcpy(, 
sprintf), and strtokC) simply don’t ex- 
ist in Clipper, FoxPro, or Visual Basic. 
However, many APIs provide alternate 
functions. Consider memcpy(): The Fox- 


Pro API includes a function _MemCpy(), 
and the Clipper standard library includes 
an undocumented internal _bcopyQ). 

To make WRAPI more C-friendly, I 
developed a strategy of wrapping C stan- 
dard functions with a macro of the same 
name in upper case. Thus, memcpy() 
became MEMCPY(). The macro trans- 
lates to the C standard function or to 
the corresponding API function. Where 
an API didn’t provide the equivalent C 
standard function, I wrote one. Table 2 
lists the C standard functions that I in- 
clude with WRAPI. You may wish to 
add to the list. My goal was to minimize 
dependence on the C standard library, 
so the list remains quite short. 
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#include <stdio.h> 


class X 
{ 
public: 
int *px; 

X( int init ) 
{ px = new int; 
“X() { delete px; } 
‘3 


void print( X x ) 
{ printf( “%d\n”", 





int main() { 
X x(15); print( x ); 
X y(16); print( x ); 
return 0; 


} 








PC-lint for C/C++ will catch this and many 
other bugs. It will analyze a mixed suite of C 
and C++ modules to uncover bugs, glitches, 

quirks and inconsistencies. 


Numerous C++Warnings and Messages: 
Are your inherited destructors virtual? Are 
your constructor new’s matched by your 
destructor delete’s? Are your initializers 
in order? Are names inadvertently hiding 
other names? Are your C++ modules 
consistent with your C modules? Much, 
much, more. 


Plus Our Traditional C Warnings: 
Uninitialized variables, unaccessed variables, 
possibly uninitialized variables, strong type 
mismatches, indentation irregularities, loss of 
precision, strange uses of Booleans, 
signed/unsigned mismatches, suspicious 
expressions, unused macros, etc. etc. 


PA add 6% sales tax. 
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*px = init; } 


*x.px ); 


print( y ); 


The output the programmer expected to see was 15, 15, and 16. Instead, he got 
[5, 16, and 16. What went wrong? Call if you need a hint. Refer to Bug #1733. 
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PC-lint users: call for update pricing 
Unix and Mainframe programmers: 
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You may notice the low-level I/O func- 
tions deviate slightly from the strategy of 
wrapping standard functions in upper- 
case macros. The open() function be- 
came F_OPEN_RW(), F_LOPEN_ROQ), 
and F_LOPEN_WO(). Likewise, /seek() 
became F_GOBOF(), F_GOEOF(), F_ 
GOTOQO), and so on. Low-level I/O flags 
differed among the supported APIs, and 
the easiest solution was to eliminate them 
entirely by creating multiple macros. 


Memory Allocation 
The next order of business was to pro- 
vide a uniform method of memory al- 
location. The malloc() function cannot 
be used in all APIs. Again, the main cul- 
prits are the Xbase dialects. Both allo- 
cate memory using an API function that 
returns a handle. The handle is easily 
decoded to an address. When it is time 
to free the memory, it is the handle that 
must be supplied, not the decoded ad- 
dress. Thus, the handle must be retained 
somehow. 
The WRAPI library includes ALLOC() 
and FREE() macros. ALLOC() increas- 
es the size of each memory allocation 
by six bytes and returns an address six 
bytes in from the actual start of allocat- 
ed memory. The first six bytes are used 
to store a 4-byte handle (if needed) and 
a 2-byte length. This allows FREE() to 
function transparently. 


Printing 

Under DOS, printing is handled through 
low-level I/O functions. This allows 
printing to be directed to either a de- 
vice or a file. Under Windows, printing 
to a file is also accomplished through 
low-level I/O, but printing to a print de- 
vice requires calls to GDI functions. 

In designing WRAPI, I adhere to the 
DOS printing model. Four constants are 
used to specify the print devices PRN and 
LPT1 through LPT3 (no support for COM 
devices other than a redirected PRN). 
These constants all have negative values. 
This allows a single function to be used 
when selecting a print destination. Either 
a valid device constant or a file handle 
(a positive number) can be passed. 
WRAPI then decodes this information into 
the appropriate print destination. 

Like many things in WRAPI, the print 
destination requires a wrapping struc- 
ture. Figure 3 shows the WPRN struc- 
ture. Under DOS it is sufficient to store 
the file handle and a Boolean flag indi- 
cating that output is directed to a stan- 
dard print device. Under Windows it is 
also necessary to store the HDC (han- 
dle to a device context) and the state of 
the spool flag in WIN.INI. (WRAPI au- 
tomatically turns the spooler off before 
printing and restores it to its previous 
state when finished.) 
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ingenuity in developing ways of 
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ware distribution, network license 
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(continued from page 30) 

The WRAPI print functions are listed 
in Table 3. After receiving the desired 
print destination (in the form of a signed 
integer) from the host application, iW- 
PrnStart() must be called to decode the 
destination into a WPRN structure. If the 
destination is a standard device, iW- 
PrnStart() opens the device under DOS, 
or creates an HDC under Windows. 
When printing is completed, iWPrn- 
End) must be called to clean up. Fail- 
ure to call iWPrnEnd() under Windows 
will result in an orphaned HDC— a very 
bad idea. 

The remaining print functions are 
used to send data directly to the print 
device. No effort is made to format out- 
put under GDI. All output is sent via 
the GDI Escape() function as DEVICE- 





Figure 3: The WPRN structure. 





Table 2: C standard functions included with 





Table 3: WRAPI print functions. 
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DATA. This effectively turns Windows 
printing into DOS printing. Incidental- 
ly, this is also the reason the print spool- 
er must be turned off. 


Error Handling 
The error handling in WRAPI reflects 
my belief that the return value of a func- 
tion should not be the source of error 
information. WRAPI provides an error- 
trapping mechanism that delivers the er- 
ror to the host API in the most appro- 
priate manner. Table 4 lists the different 
error mechanisms employed by WRAPI. 
The biggest compromise in error han- 
dling is caused by host APIs that don’t 
have a standard error-trapping mecha- 
nism. In such cases, it is necessary for 
the host application to pass a function 
reference to the core library. The core 





WRAPI. 


es 






library must then make that function 
reference available to the WRAPI error- 
trapping mechanism. The error trap sim- 
ply calls the referenced function. Un- 
fortunately, this destroys an otherwise 
clean separation between the host, the 
wrapping, and the core. 

This shortcoming of the error system 
is best illustrated with an example. In- 
Press provides two functions: JpErr- 
FName(), which takes the name of a 
FoxPro function designated as the error 
handler; and JpErrFPtr(), which takes 
the address of a C function (cast as a 
long) designated as the error handle. 
Failure to register an error function with 
IpErrFName() under FoxPro or IpErr- 
FPtr() under C effectively defeats In- 
Press error handling. In effect, the ap- 
plication is blind to In-Press errors. 

Error handling blurs the line between 
the core and the wrapping. All core li- 
braries must follow certain error con- 
ventions and provide a standard set of 
error macros to the wrapping functions. 
These macros, listed in Table 5, act as 
a call back into the core library. Listing 
Six (page 90) is an In-Press wrapping 
function and its corresponding C trans- 
lation. Note the references to the In- 
Press error-handling internals. 


GET/SET Functions and Nil Values 

A WRAPI library design is constrained 
by several factors. For one thing, the 
names of wrapping functions are limit- 
ed to ten characters (as are the names 
of any support constants). This limita- 
tion is imposed by FoxPro, and there is 
no way around it. More importantly, the 
data types are limited to the six basic 
ones listed earlier: character, string, 
Boolean, short integer, long integer, and 
double float. 

In C, there is a tendency to keep re- 
lated data in a structure. This works 
nicely because the structure can be 
passed by reference. WRAPI precludes 
that type of interaction between a core 
library and the host API. How then do 
you structure a useful library if data 
moves in and out as simple data types? 

My solution was to store the data 
structure internally and provide discrete 
access to each component with a GET/ 
SET function. For those unfamiliar with 
the term GET/SET, it is a function that 
can simultaneously change the state of 
an internal value while returning its pre- 
vious state. A GET/SET function can also 
query the state of an internal value with- 
out actually changing it by passing a 
NIL value. 

Although you don’t need to use 
GETYSET functions in the design of a 
WRAPI library, they are quite useful. 
WRAPI includes logic for NIL values and 
a sample GET/SET engine. 
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(continued from page 32) 

Necessary Tools for WRAPI Development 
Table 6 lists all of the tools needed to 
develop and test a WRAPI library. It is 
no small undertaking. In addition to pur- 
chasing and installing the listed prod- 
ucts, you will want a mechanism for au- 
tomating the build process. A set of 
batch files and a sample makefile are 
included with the source diskette to help 
you get started. 


Writing WRAPI Functions 

Any library requires a bit of planning. 
WRAPI simply adds to the process. The 
general scheme for developing a WRAPI 
library is: 


1. Map out the function list. 
Z. GET/SET functions wh 
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sible. Functions that need to return 
composite values (such as arrays or 
structures) can either return them 
as strings (using the WRAPI stringi- 
JyO function) or divide the return 
values among several GET-only 
functions. 

3. Create function prototypes and con- 
stant definitions for the various lan- 
guages. 

4. Map out which functions will be in 
which source files. 

5. Write the core error-handling func- 
tions first. (They should be patterned 
after the error-handling functions in 
the sample library.) 

6. Write the error-wrapping functions 
and test them in a couple of lan- 
guages. 

7. If you'll be using GET/SET functions, 
set up the GET/SET engine. 

8. Write any other core functions that 
are required for underpinning the li- 
brary. 

9. Write wrapping functions in related 
groups. Debug under DOS first — C 
is easiest. Next debug under Win- 
dows—Visual Basic works well. Al- 

- Ways test in FoxPro. 

10. When the library is ready to ship, 

compile using optimization. 





Testing and Debugging WRAPI Functions 
It can take time to test a WRAPI library. 
Each change to a library must be tested 
under the numerous languages. It is 
not uncommon to spend an entire af- 
ternoon checking the results of a func- 
tion that took only one hour to write. 
WRAPI certainly doesn’t lend itself to 
an ad hoc development cycle. After 
you gain familiarity with WRAPI de- 
velopment you learn where to take 
some shortcuts. (If it works under Clip- 
per and FoxPro for Windows, for ex- 
ample, it probably works under every- 
thing else.) 

WRAPI development seems to yield 
robust libraries. The various host APIs 
expose different types of problems. I 
found that general debugging was eas- 
iest in the DOS environment using C or 
Clipper as the host language. Once all 
of the obvious errors were exorcised, it 
was on to the protected-mode lan- 
guages, either FoxPro for Windows or 
Visual Basic for Windows, to find the 
memory violations. I was able to use the 
CodeView debuggers quite successfully. 


Conclusion 

WRAPI is a work in progress and there 
are shortcomings to the technology that 
you may want to improve. For instance, 
parameters must be passed by value, al- 
though it should be possible to wrap pa- 
rameters passed by reference. WRAPI 
has no mechanism for wrapping inter- 
rupts. The general lack of C standard li- 
brary functions will certainly impede 
conversion of existing libraries to WRAPI. 
Also, WRAPI has not been extended to 
OS/2, NT, or UNIX. 

There are several inherent limitations 
to WRAPI. The ten-character limit on 
symbol names can make function and 
support constants a bit terse. 

The technology is not quite a “black 
box.” Thus, the WRAPI developer is re- 
quired to understand the APIs of the sup- 
ported languages. And WRAPI functions 
are by their nature limited to “driver” 
type applications. Proprietary hooks into 
a particular O/S or a development envi- 
ronment defeat the purpose of WRAPI. 

Even with these limitations, WRAPI is 
a good starting point if you need to sup- 
port multiple languages. The source files 
include everything you need. I will 
maintain and update WRAPI on the 
CompuServe DDJ Forum. I hope you 
will join me there as I answer questions 
and attempt to improve the technology 
based on the suggestions of other 
WRAPI developers. 


DDJ 


(Listings begin on page 89.) 


To vote for your favorite article, circle inquiry no. 2. 


Dr. Dobb’s Journal, March 1994 



























It’s time for a truly objective discussion about 
application development. IBM’s System Object 
Model (SOM) (currently shipping with OS/2® 2.1) 


is a language- -neutral mechanism for 
before. 


developing object-oriented class 
libraries. Together with our _—_ 
IBM SOMobjects" ( 
OMobjects tools let you take full advantage 
of the object-structured protocol of SOM~—applications 
can access and use objects and object definitions regardless 
of what programming language created them. Now reuse isa 
reality. Instead of recompiling apps due to implementation 
changes, just reuse the objects. That saves time and ge | 
money. And SOMobjects incorporates 
Distributed SOM (DSOM) technology 
to provide a base for object-oriented 
programming development and use over 
entire networks. What devel- 4 
‘ , Oper could object to that?” 



















ndards of the Object | 
a Common Object 


CME EE. Sa ANON ® 
MAA AA A | ANNAN 
Bo = a A =A 
IBM and OS/2 are registered trademarks and AIX/6000 and SOMobjects are trademarks of a, oan. “cae eee oe 
International Business Machines Corporation. All other products are trademarks or registered ae = a ey an 
trademarks of their respective companies. ©1993 IBM Corp. oe —— aa 4 a 


CIRCLE NO. 899 ON READER SERVICE CARD 








Multiplatform 


ANI Files 





Portable profile 
functions 





Joseph J. Grat 


ortable-interface toolkits allow you 
to write code once and recompile 
with the appropriate libraries for 
other target platforms. Most of these 
interface libraries are implemented with 
a lowest-common-denominator feature 
subset. This means that if you depend 
heavily on a specific operating-system 
feature, the only option available is to 
develop your own portable version of 
the routines. 
One of the features in the Windows 
API that I continually rely on is its pro- 


file functions, which encapsulate the read- 7 


ing and writing of information to .INI 
files. For example, I often use .INI files 
to maintain a list of last-used settings for 
“smart” dialog boxes. This feature has 
been so popular in the Windows version 
of my applications that I implemented 
the same for my DOS and UNIX pro- 
grams. The routines presented in this ar- 
ticle are portable versions of the Win- 
dows functions GetPrivateProfileString(, 
GetPrivateProfilent(), and WritePrivate- 
ProfileString(). My functions only work 
with private profile strings for the ob- 
vious reason that other operating envi- 
ronments do not have a WIN.INI file. 


Reading from the .INI File 
To read an entry’s value in a section of 
an .INI file, you use my functions get_ 


Joe has been programming for eleven 
years. He is currently working on an 
embedded system, writing PC and Win- 
dows-based development tools for the 
embedded OS. He can be reached at 
jg@usorder.com. 
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private_profile_int() and get_private_ 
profile_string(). Listing One (page 91) 
presents the header file which contains 
the prototypes to these functions. The 
two functions use the same parameters 
as the equivalent Windows versions, al- 
lowing you to incorporate them easily 
into your existing code. You can use 
#ifdefs at the point of call, as in Exam- 
ple 1. Alternately, you can use #defines, 
for example, to make get_private_pro- 
file_string resolve to GetPrivateProfile- 
String when compiling for Windows and 





to remain unchanged when compiling 
for DOS and UNIX. Thus, you can main- 
tain a single source module for multi- 
ple platforms— at least in the case of 
profile-string manipulations. 

Windows .INI files are divided into 
sections and entries. A section appears 
within the file as /section_namej, fol- 
lowed by any number of entries using 
the format entry_name=entry_value. 
For example, the /ports/ section of your 
WIN.INI file contains entries such as 
COM1:= 9600,n, 8, 1,x. 

So the first task in obtaining an entry’s 
value is to find the appropriate section 
within the file. Your code passes the sec- 
tion name to either of the GetPrivate- 
Profileint or ...String functions as a reg- 


ular string, for example, "section_name". 
The Windows function then turns this 
parameter into ‘/section_name/". Like- 
wise, get_private_profile_int() and get_ 
private_profile_string() also enclose the 
section-name parameter within square 
brackets. Once the section-name string 
is in the correct format, the routines 
search the .INI file line by line until a 
matching section name is found. If one 
is not found, the value specified in the 
default parameter will be returned for 
the integer function; the string function 
copies the default string into the buffer 
and returns the default-string length. 

If the correct section was found in the 
INI file, the profile routines search for 
a matching entry. The entry name is 
compared up to the equal sign using 
the length of the entry parameter. If the 
search traverses the section without find- 
ing the specified entry, the default val- 
ue or string is returned. If an entry is 
found, a pointer is set to point to the 
value portion of the string. The get_ 
private_profile_int() function copies the 
entry’s value string into a temporary 
string buffer as long as the entry con- 
tains numbers, then returns the numer- 
ic value of the string using the standard 
library function atoi(). The get_pri- 
vate_profile_string() function copies the 
value portion of the entry to the buffer 
up to a maximum of buffer_len char- 
acters. If the entry contains more char- 
acters than the buffer can hold, it is trun- 
cated to prevent memory overruns. This 
function returns the number of charac- 
ters copied into the buffer. 


Writing to .INI Files 

The Windows profile routines only sup- 
port the writing of strings to .INI files. 
To maintain compatibility with the Win- 
dows routines, my code has the equiv- 
alent limitation. In the effort to keep the 
code straightforward, my write function 
creates a temporary file and copies the 
INI file to it, as the .INI file is read and 
searched. At the end, when the file has 
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Example 1: Calling a routine to read a profile string, using a compile-time 
conditional to invoke either a Windows version or a portable version. 


(continued from page 30) 

been completely written, the old .INI 
file is unlinked and the temporary file- 
name is changed to the supplied file- 
name. This may not be the most effi- 


cient method, but it was easy to imple- 
ment and will be easy to maintain. 
The write function tries to open the 
file for reading first. If it can’t do so, the 
file must not exist, so write creates one 
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and then writes the section information, 
followed by the entry and its associat- 
ed string. 

The write_private_profile_string() 
function searches the .INI file for the 
correct section as with the get functions, 
but this function copies its input to the 
temporary file as it goes. If it never finds 


You can maintain a 
single source 
module for multiple 
platforms—at least 
in the case of 
profile-string 
manipulations 





the section asked for, the function ap- 
pends the section and entry to the end 
of the file. If the function finds the cor- 
rect section, it then searches for the 
correct entry, copying the file in the pro- 
cess. If the end of the section comes 
without finding the entry, my routine 
adds the entry at the end of the section, 
and the remainder of the file is then 
copied. In the case where the entry was 
found, its old value is discarded, re- 
placed by the value passed into the 
function. 

Listing One contains the prototypes 
for the functions plus the #define MAX_ 
LINE_LENGTH, which is currently set at 
80. Listing Two (page 91) implements 
the functions read_line(), get_private_ 
profile_int(), and get_private_profile_ 
string(). Listing Three (page 91) con- 
tains the write_private_profile_string() 
function. 

These functions were designed for 
ease of reading. There are places where 
the code could be made smaller by cre- 
ating subroutines from redundant code, 
although the savings would be nominal 
at best. Also, you could write addition- 
al functions to handle reading/writing 
longs, floats, and so on. I didn’t imple- 
ment these additional functions because 
Windows itself does not support them, 
and compatibility was of utmost im- 
portance. The goal of write-once-port- 
many is often elusive, but achieving it 
in this particular case is not too difficult. 


DDJ 
(Listings begin on page 91.) 


To vote for your favorite article, circle inquiry no. 3. 
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Mapping structures are 
one place to start 


Michael Ross 


@ hen it comes to writing software 
1/7 for multiple operating systems 
(J/ and microprocessors, you really 
— only have two choices: design 
soitabilin into your code from the start, 








or de facto standard, your code is auto- 
matically portable. If they’re a bit more 
savvy, they may allow that you need 
some kind of platform-specific GUI- 
development package. These are the 
same people likely to storm into your 
office when you tell them that it will 
take six months and a rewrite of some 
modules to port application XYZ to a 
new platform. 

To keep tempests out of your office, 
here are some things to think about 
when writing code: 


or wait until you are forced into ex- 4 \) 


pensive rewrites. 


Where I work (MetaWare), we often @ 


have to quickly port a compiler from 
one platform to another. It isn’t unusual 


to have a compiler that compiles itself 773 


on the new platform (that is, a particular 
processor/OS combination) in six to 
eight weeks, with one to two people 
working on the project. This is possible 
because portability— the ability to com- 
pile, run, and achieve close to the same 
results as well as the same look-and- 
feel across platforms— was designed 
into the compiler from the very begin- 
ning. In this article, P’ll discuss some of 


the techniques we’ve developed that & 
you can use to enhance the portability 


of your code. 

MetaWare got started in the compiler 
business in 1983 because we were hav- 
ing difficulty porting our parser genera- 
tor to various Pascal compilers. These 
problems motivated us to write a port- 
able compiler of our own. In moving to 
various processors and operating systems, 
we distilled some knowledge of the prob- 
lem areas in writing transportable code. 

Some people believe that if you write 
in C or C++ and stick to the latest ANSI 


Michael is a senior compiler developer 
for MetaWare with over 16 years of 
compiler development and management 
experience. He can be contacted at 408- 
429-6382. 
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e Don’t delay coding for portability. 
There’s a temptation to say “I’ll get it 
working on one platform, then wor- 
ry about the others.” If you take this 
approach, you could find yourself do- 
ing a significant rewrite. 

Assume your application will live for- 
ever. Try to predict which platforms 
your application might port to in the 
future, and take their peculiarities into 
account. 

Isolate the user-interface portion of 
your code from everything else. Try 
and perform an abstraction so that the 
rest of the application doesn’t know 
whether it is writing to a dumb ter- 
minal, working with X Windows, or 
interacting with Microsoft Windows. 


by Design 


e Stick to ANSI standard or very widely 
implemented features in your source 
code. For C++, avoid using templates 
and exception handling, since these 
constructs are not widely available. 
Use your compiler’s ANSI checking 
switch for any language that has an 
ANSI standard. This isn’t a cure-all, 
but it does help. Use some form of 
lint, and take the warnings seriously. 
Make your code compile with no 
warnings. 

Are all the tools you need available 
on each platform? Assembler? Profil- 
er? Debugger? GUI manager? We fre- 
quently find buggy assemblers when 
we port. 

Make code involving floating point 
tolerant of answers that lie within a 
known correct range. To see if your 
code is likely to have problems in this 
area, compile it with two different 
compilers on the same architecture. If 
the results vary at all, then moving the 
code to a new architecture is likely to 
magnify the differences. 


Listing One (page 93) shows a struc- 
ture used to encapsulate machine and 
Operating-system dependencies. The 
mapping structure, with its associated 


™ macros, communicates dependencies 


between our C or Pascal front end and 
the code generator for the target pro- 
cessor. You can broadly categorize the 
platform characteristics encapsulated in 
this mapping structure as: 


e Alignment of data. 

e Special machine instructions, such as 
transcendentals. 

e Size of various fundamental data types. 

e “Endianness,” or byte order. 

e Floating-point format. 


Listing Two (page 94) includes an 
ideal representation of a floating-point 
number, with a mantissa of 128 bits. The 
compiler uses this for internal manipu- 
lation of floating-point constants and 
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programs will 1 
80286, 386, 486 


. _ no special programr 
- aPhar Lap DOS ext 


developers: every copy 
new VisualC++ 
Professional Edition - 
includesaFREE — § 
trial-sized Phar Lap® ~ e 
DOS extender! Phar 
-Lap’s 286|DOS- 
Extender” Lite is a 
special version of — 
Phar Lap’s award- -winning + 286ID0S- 
Extender. With 286IDOS-Extender Lite, 
you can write DOS programs that break 
the 640K barrier, access up to 2 MB of 
- memory, and run under DOS, 
DESQview’, Windows” and OS/ 0 It’s 
the easiest introduction you'll find to 
Extended- DOS programming. 


Build multi-megabyte, 
full-featured DOS 


programs — 2861D0S- 
Extender SDK. 

Professional developers can 

purchase Phar Lap’s full- RVIE 
featured 286|DOS-Extender =m 


SDK for $495. With the — 
286|DOS-Extender SDK, you 

can access up to 16 MB of — 
memory — with the standard PYTE 
Microsoft or Borland tools ae 
you already use! The new eres 
Version 3.0 of 286|DOS- 

Extender now supports 


Visual C++ as well as 
Microsoft C/C++, Borland® 
C++ and Microsoft Fortran. 
You can even use Microsoft's 


PRODUCTIVITY 
771. 
1990 


CodeView” or Borland’s 
Turbo Debugger® to debug STE 
your Extended-DOS 






programs. 286IDOS-Extender 





can access extended 


were conventional (below 64( 
_ memory. _ 


og6IDOS Extender is one af tomes 
- widely used 16-bit DOS extenders | 


available. If you’d like to know why, take 
a look at what our customers and other 
industry experts have to say about the 
286IDOS-Extender SDK . Then find out 
for yourself by trying the free 286ID0S- 
Extender Lite — or get started right _ 
away on your multi-megabyte DOS 
applications with the professional 
286IDOS-Extender SDK! — 


What the experts say 
about Phar Lap’s 
286|DOS- Extender SDK: 


“Great tools for Visual C++ 
programmers who need 


more memory” 
- Denis Gilbert, Microsoft Corp. 


“A no-compromise solution 
for Borland C++ developers” 


- Paul Gross, Borland International 


“An excellent product 
technically” 


- Glenn Axworthy, Broderbund Software — 


“Gives our customers the 


memory they need” 
- Bert Love, Galacticomm, Inc. 


“A superb way of utilizing all 


available memory” 
- Dave Jewell, Program NOW, August 1991 


in your eonipiter 286IVMM c: can improve — 


the performance of applications at 
previously relied onloading and 
unloading dynamic link libraries OLIs). 


— And it’s fully DPMI-compatible, so _ 


programs running under Windows | 
automatically use the virtual memory — 
provided by Windows. 





NEW! TNT DOS-Extender- 
Get NT Power under 
32-bit DOS! 


If you want 32-bit speed and 

performance, as well as powerful new 
NT features for your DOS applications, 
Phar Lap’s TNT DOS-Extender is the 
answer. With TNT, you can use your 
familiar Microsoft Visual C++ 32-bit 
Edition compiler to write programs that 
run in a workstation-like, unsegmented 
32-bit address space while implementing 
threads, DLLs and multitasking. It’s 
never been so easy to create the most 
pe ee DOS | pr 








~ Phar Lap Software, Inc. 


60 Aberdeen Avenue, Cambridge, MA 02138 617-661-1510 bee 617-876-2972 


286IDOS-Extender and TNT DOS-Extender are trademarks and Phar Lap is a registered trademark of Phar Lap Software, Inc. Borland and Turbo Debugger are registered trademarks of Borland International. Visual C++,Windows 
and Windows NT are trademarks and CodeView and Microsoft are registered trademarks of Microsoft Corp. Other product and company names are trademarks or registered trademarks of their respective holders. 
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srapnics 


Would Text and Graphic 
Printer support for over 850 
printers give you an edge? 


By including SLATE with Graphics, you 
can print Text and Graphics on over 850 
printers. Immediately! Painlessly! 


You can use SLATE in your product 
with no royalties. It gets you out of the 
printer support business. 


Make your product more functional 
and competitive by using SLATE's 
advanced text features: 

* Output to parallel printers, serial printers, DOS 

files and Novell network printers. 

¢ Support proportional fonts and scalable fonts. 

* Set exact print positions. 

¢ Kerning, leading, underlining, and strike through. 

¢ Automatic character set conversion. 

* Print lines and shaded areas (laser printers only). 


SLATE with Graphics adds advanced 
graphic printing features: 

¢ Print images from the screen, PCX or TIFF files, 

or custom image systems. 

¢ Print lines and shaded areas on all printers. 

* Scale and Rotate printed image. 

* Print grey scale and color images. 

* Intermix text and graphics. 


SLATE is a C or Basic library of over 
170 text printing functions, a Database 
of over 850 printers, and End User 
configuration and testing programs. 
SLATE with Graphics adds over 60 
graphic printing functions. 


Would a User Configurable 
Report Writer give you a 
more competitive product? 


SCRIPT is a full featured Text 
Formatting library that can be 
incorporated into your application. 
SCRIPT uses SLATE as its printer 
driver. SCRIPT lets you merge text, 
data, and S_PRINT formatting 
commands from ASCII files and your 
application. 


Enhance your product by taking 
advantage of SCRIPT's features: 
¢ Allow users to alter document format. 
* Set exact positions, center, right adjust, and 
decimal align. 
¢ Fill paragraphs from unformatted text. 
¢ Add lines, shaded areas, logos, signatures, etc. 
¢ Add commands and macros. 


Call or FAX now for a complete catalog 
and developer's guide for The 
Symmetry Group's printer support 
products. Order SLATE for $299, 
SLATE with Graphics for $448, or 
SCRIPT for $199 with our risk free, 30 
day return policy. 





3 431. 2667 : FAX 614. 431- 5734 
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(continued from page 40) 

then converts them to whatever exter- 
nal floating-point representation is re- 
quired on the target machine. The code 
uses the knowledge of the longword 
size of the host machine where the com- 
piler is running to assure that we don’t 
shift by an amount that will yield invalid 
results on the host system. 

Your code should contain safety 
checks to prevent you from relying too 
much on a particular word size or 
floating-point representation. 

The problem with code that does a 
lot of floating-point calculation is that 
the precision of the results and the 
execution speed of the code may vary 
widely from one architecture to another. 
Even on a machine that has some vari- 
ation of IEEE floating point, the defaults 
as to which kinds of overflow traps are 
signaled or ignored can vary. On the 
80387 and Motorola 68040, the varying 
frequencies with which compilers store 
floating-point results to memory can sig- 
nificantly affect the accuracy of your re- 
sults. Are the potential target platforms 
flexible — through library calls or some 
other mechanism— in determining how 
rounding will occur, when results are 
stored, and what traps are signaled? If 
not, you should consider implementing 
your own a ed sso one: 


a CONTINUE oo. 
END 


Example 1: (a) Bad code that 
intentionally demonstrates problems 
in alignment; (b) nonportable Fortran 
code which will compile and run on 
some architectures, but on others will 
cause a trap at run time; (c) Fortran- 
90 encourages automatic allocation 
of local variables. 








point operations. The MetaWare C com- 
piler, for example, maintains its own in- 
ternal version of a floating-point con- 
stant and constant operations. When 
necessary, the compiler converts float- 
ing-point constant results to the repre- 
sentation of the target architecture. 

“Portable” applications should have 
roughly the same look-and-feel across 
platforms. When you port an applica- 
tion that is interactive and heavily de- 
pendent on floating point (a CAD 
package, for example) to a new ar- 
chitecture, some algorithms run too 
slowly. This is because they depend- 
ed upon some capability of the origi- 
nal architecture (such as built-in tran- 
scendental instructions) for reasonable 
run-time performance. With the trend 
toward RISC architectures, you may 
want to examine your code for such 
hot spots and change the algorithm. 
You might even write your own tran- 
scendental routines to insulate the ap- 
plication from performance changes 
across platforms. 

Alignment of data is a problem main- 
ly when your application depends on 
transmitting binary data across plat- 
forms, or uses different language pro- 
cessors on the same platform. Aside 
from the obvious endianness difficul- 
ties, there are variations in field align- 
ment. This often necessitates repre- 
senting the binary data in textual form 
or having a data broker perform the 
necessary transformations between the 
two architectures. Consider the “bad” 
C code in Example 1(a), which was 
intentionally written to demonstrate 
alignment problems. The alignment of 
the various structure fields will vary 
from one compiler to another and 
from one architecture to another. 
Imagine trying to write this to a bina- 
ry file and read it back on another 
platform! Even with the same language 
processor, this structure will vary in 
size, due to memory “holes”; for ex- 
ample, on SPARC sizeof(mystruct)=24 
bytes, on 80386 sizeof(mystruct) =16 
bytes, and on HP-PARISC sizeof(my- 
struct)=24 bytes. 

The problem is worse, of course, in 
languages like Fortran. If you write code 
like that in Example 1(b), it may com- 
pile and run on some architectures, 
while others will cause a trap at run 
time. On the Intel i860 processor, doing 
a load of a double- precision value that 
is not aligned on a double-precision 
boundary is difficult and slow, and some 
compilers don’t support it. Other RISC 
architectures have similar problems. 
Note that the Fortran code in Example 
1(b) fits within the ANSI standard; it 
does not fit our definition of portabili- 
ty, however. You should examine your 
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data structures, regardless of the pro- 
gramming language you use, and en- 
sure that structure and union fields are 
aligned on common, natural boundaries. 

There may soon be some light on the 
horizon to help with some of the binary- 
data compatibility problems, in the form 
of SOM (system object model), which 
allows a common binary format for 
objects across architectures and lan- 
guages. SOM meshes with the activities 
of CORBA, which may eventually allow 


Some people believe 
that if you write in 
C or C++ and 
stick to the latest 
ANSI or de facto 
standard, your code 
is automatically 
portable 





different C++ compilers to share a com- 
mon object format. — 

The Fortran programming community 
that depends on de facto characteristics 
of old compilers may be in for a rude 
shock as vendors write new Fortran-90 
compilers. I’m always amazed at code 
such as that in Example 1(c) that lives 
on in many applications. This code de- 
pends on zero initialized memory and 
static allocation of local variables. With 
its RECURSIVE keyword and name- 
space rules, Fortran-90 encourages auto- 
matic allocation of local variables. Most 
optimizers will not perform up to their 
potential if you use statically allocated 
variables. 

C programmers are not exempt from 
writing absurdities, either. The most 
common used to be the use of the reg- 
ister specifier. Most optimizing compil- 
ers now ignore the register specifier al- 
together. If you move your code from 
one architecture to another, you can't 
expect the same set of variables to be 
maintained in registers across architec- 
tures. Usually, the register allocator can 
do a better job than a person of choos- 
ing registers and keeping the choices 
optimal as the source code changes. 


Operating-system Dependencies 

Occasionally, an application has to 
manipulate data that is inherently 
Ooperating-system dependent. Listing 
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Three (page 94) shows a class defi- 
nition for managing processes. This 
code encapsulates everything your 
application might need to know about 
a process, regardless of the underly- 
ing operating system. Note that oper- 
ating-system dependent actions such 
as stepping the process by an in- 
struction are deferred to member func- 
tions that can be extremely operating- 
system specific. The remainder of the 
application, however, uses these op- 
erations through the class definition 
in Listing Three, allowing you to iso- 
late the OS-specific code from the 
rest of the application. Virtual func- 
tions (which are not used here) can 
also help you to isolate system de- 
pendencies by allowing you to fill in 
a specific member function that match- 
es a particular OS. 


User-interface Dependencies 

If the application’s user interface is more 
complicated than a simple command- 
line switch interpreter, you'll need to 
consider a GUI manager. Since X Win- 
dows is available on almost all UNIX 
systems, you could create a relatively 
portable system by taking into consid- 
eration X Windows, Microsoft Windows, 
OS/2, character-based MS-DOS, and Ap- 
ple Macintosh. However, if you can find 
a reliable vendor who has already en- 
capsulated these APIs for you, it’s prob- 
ably worth your money to buy the class 
libraries. Be aware, however, that some 
GUI vendors depend on a Motif layer, 
which is not supplied with the product, 
and not bundled with the OS by many 
vendors. 

Another consideration in GUI class- 
library selection is the trend toward soft- 
ware internationalization. If possible, 
examine the source code and see how 
hard this is going to be for you. A good 
technique is to group all of the mes- 
sages that a user might see in a single 
table or separate resource file. Then 
the input and output can be translated 
without affecting the remainder of the 
application. If your system allows, you 
may even be able to have different na- 
tional-language versions of the user in- 
terface in DLLs that can be loaded on 
demand. 

Taking all of these different factors 
into consideration as you write a new 
application or port an old one seems 
like a lot of extra effort. However, if 
you design portability in from the be- 
ginning, you'll save yourself a lot of ef- 
fort later. 


DDJ 
(Listings begin on page 93.) 
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Find what you nee : code! 

You port code to new languages or 
platforms and maintain critical legacy 
code. You could spend hours slogging 
though printouts trying to figure out 
where a function is called, or tracking 
down that elusive variable assignment. 
Or you could use Source Print and 

ot ote your code to feature exactly the 
information you need! Use Source Print’s 
exclusive multi-file cross reference and 
generate a single comprehensive index 
that details not just where, but how all 
identifiers, variables and functions are 
used in all the files in your project. Or 
create a function call tree diagram that 
graphically details what each function in 
your program does. Source Print helps 
you get every iota of information from 
existing source code. 







Organize your code for reuse! 

What good is object-oriented code if you 
can’t disentangle it and use it again? Use 
Source Print to extract a single function 
from a huge source file, and save it toa 
file or send it to your printer. Add 
Powerline’s Source Control to your system 
and you are efficiently creating version 
control archives to build new software 
enterprises! 


Freedom to code your own way! 

When you use Source Print on new code, 
especially as a part of a development 
team, there’s no need to worry about 
finding a particular style that suits 
everyone. Install multi-user Source Print 
on your network and run your "code 
complete" through the formatter before 
passing it along to your boss! And when 
you need to review someone else’s code, 
just format it the way that you find 
easiest to work with. 


The original is still the best 

Source Print has been around since 1986. 
It’s made the same transitions that you 
have in terms of "popular" languages. It 
can easily handle the code you wrote in 
BASIC five years ago and the code your 
are writing in C++ now. In fact, Source 
Print supports C, C++, BASIC. xBase, 
FoxPro, Clipper, Pascal, FORTRAN, and 
Modula-2 in one package. You get both 
DOS and Windows versions in one 
package so whether you are a hardcore 
DOS programmer or a cutting-edge 
Windows developer you use Sourc 
to get a handle on your code. 


Print 







VERSION 6.0 NOW AVAILABLE 
Powerline has just released version 6.0 of 
Source Print. Call for your upgrade today! 


SOURCE PRINT 


The multi-language, multi-platform 
code management tool 


1-800-257-5773 


SOFTWARE 


1306 Western Avenue, Suite 203, Seattle, WA 98101 
Voice: 206-623-9204 Fax: 206-467-6561 
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Die Neue 
Druckergeneration? 


D ie japanische Firma Tizamimateu 
~ stellte auf der Messe wloh Und| * 

Mein Geld«, kurz IUMG die Druk- 

kergeneration der Zukunft vor, Die 
entecheidenden Anderungen ge gen- * 
ruc.| Betriebssystem im 





Zusatzlioh werden einige Tools rum 
Komprimieren der 48 KB grofen 
FAT und der Mediumkennung, die 
ebenfalls 48 KB belogt, mitgeliefert, 
Die Verwendung von Funktionsbe- 
fehlen wurde weiterhin optimiert und 
auf 3 Befehle verringert, Dadurch ist 
der Umstiog auf dieses Batriebesy- 
stem ungewohnlich einfach. Zu den 
Befehlen gehdren weiterhin DIR, 
UNDELETE und FORMAT C: 


& @__Ablage a Rasicht cab tn Format Extras Fenster Hilfe 
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Zusatzlich werden einige Tools 
zum Komprimieren der 48 KB 
groBen FAT und der 
Mediumkennung, die ebenfalls 
48 KB belegt, mitgeliefert. Die 
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fehlen wurde weiterhin opti- 
miert und auf 5 Befehle verrin- 
gert. Dadurch ist der Umstieg 
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YOU ONLY HAVE TO 
WRITE IT ONCE WITH 
STARVIEW 2.0 


Druckergeneration? eh eee By learning StarView.™ you can write high-end applications with a 

zr single source code for all of our supported platforms with their native 
look and feel and only have to debug them once—cutting your develop- 
ment time dramatically. StarView can guarantee seamless portability 
because it was designed with a multi-platform approach from the very 
beginning, and it has always supported the latest features—necessary for 
competitive high-end applications. 








StarView 2.0 Features 
StarView has all the standard controls like Windows, Dialogs, Menus, 
and Buttons. But it also has other portable capabilities like Help System, 
Drag & Drop, OLE, Bitmaps, Toolbar, Statusline, ‘Tablecontrol, MDI, 
Printing and Preview, Internationalizing of Date, Time and Metric 
Classes, and a Multinational Resource System that allows you to create 
a single Resource file containing all international versions of your 
program. StarView also has standard dialogs for File-Handling, Printer- 
Setup, and Color- and Font-Selection. 

All controls are also available in the 3D StarView Look. And in 
addition to the program features, StarView comes standard with the 
StarView Design Editor and the StarView SFX Application Framework. 


applications to Windows, Windows NT, Macintosh, UNIX, and OS/2 environments, call 1-800-888-8527. 





Thousands of Programmers Prefer StarView 

We’ve developed the most complete and clearly implemented C++ 
multi-platform software development tools available. That’s why, even 
after trying other libraries, thousands of programmers still prefer using 
StarView—from the smallest startup to the largest computer communi- 
cations and systems integration companies in the U.S. 


Call 800-888-8527 for More Information 


If you’re interested, call us to Presi 2 8 
receive a full working democopy Windows 3.1 $498 
of StarView, with DesignEd, and Apple Macintosh $498 
the StarView Whitepaper. You'll IBM 0S/2 2.1 $498 
be able to explore the features of Windows NT/Intel $498 
StarView as well as discover how Windows NT/Dec Alpha $498 
easy it 15 to use. Sun SPARC Solaris 2.x/Motif $1498 
IBM RS 6000/Motif $1498 
Star Division Corporation DEC Alpha OSF/1 $1498 
ara Sear ae = Call for information on other platforms. 


Tel: 415.233.0140 
Fax: 415.233.0142 


E-mail: svinfo@stardiv.de 









9 
Mira fi 


TM 
STA R D IVI Si 0 N CIRCLE NO. 782 ON READER SERVICE CARD 


©1994 Stor Division Corporation. All rights reserved. Star Division and StarView are trademarks of Star Division Corporation. All other product names are trademarks of their respective companies. 















~ Unicode and 
Software Globalization 





Software-design guidelines 
Jor international 
application development 





David Van Camp 


evelopers have traditionally pro- 
duced software for the domestic 
U.S. market, then remarketed it 
overseas after a few simple modi- 
fications. This practice, however, is fast 
becoming unacceptable as more and 


more non-U.S. users expect software to 


“speak” to them in their native tongue 
and conventions. Furthermore, non-U.S. 
computer markets are growing rapidly, 
forcing software developers to begin 
thinking internationally. Currently, a va- 
riety of character standards and propri- 
etary extensions are being used to ad- 
dress application internationalization. In 
many cases, however, the result is of- 
ten inefficient code that’s difficult to 
maintain, hard to port, and expensive 
to produce— all problems the Unicode 
standard addresses. 


The Unicode Standard 

Unicode is an international character 
code standard which replaces single- 
byte ASCII and ANSI, multibyte ANSI, 
and nearly every other character-code 
standard currently defined. Unicode 
contains a one-to-one mapping of 
codes for ASCII and the ISO 8859/1 
Latin character set used by Microsoft 
Windows, NextStep, and others. Ad- 
ditionally, Unicode contains a nearly 


David is a senior consultant with Cap 
Gemini America. He specializes in Win- 
dows, NT, and OS/2 development. You 
can contact him on CompuServe at 
70529, I 510, 
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complete superset of all fixed-size and 
multibyte standards currently in use 
and provides for symbol sets such as 
mathematical operators, technical sym- 
bols, geometric shapes, and dingbats. 
The initial release of Unicode, in fact, 
contained 26,000 characters. More im- 
portantly, when producing code, the 
Unicode character standard provides 
a global solution for application lo- 
calization, which solves many of the 
problems associated with multibyte 
support. Specifically, it provides the 
ability to prepare your application 
code for supporting nearly all lan- 
guages with little or no modification, 
at least in terms of data storage. (See 
the accompanying text box entitled, 
“The Unicode Consortium.”) 

The good news is that it’s relatively 
simple to modify most applications to 
transparently support multiple charac- 
ter standards. I now support Unicode 
whenever possible in my applications. 
The degree of difficulty for supporting 
Unicode depends on which and how 
many character standards were sup- 
ported by the original code, what fu- 
ture requirements are expected, and 
how much support is provided by the 
underlying graphics engine and operat- 
ing system. 

Microsoft’s NT operating system uses 
Unicode internally to represent all char- 
acters and strings. In addition to long 
filenames and extended attributes, NT 
supports Unicode characters in file- 
names. Consequently, it’s possible for a 
single filename to contain a mix of char- 
acters from hundreds of modern lan- 
guages and even a few archaic ones. 
Fortunately, Unicode prevents our hav- 
ing to switch between character stan- 
dards to process such filenames. This 
simplifies many string operations. 


For example, in the common prob- 
lem of splitting a filename off the end 
of a fully qualified path, you typically 
start at the rightmost character and 
traverse back to the first backslash, 
colon, or the beginning of the string; 
see Example 1. 

For standards which use a variable 
number of bytes per character (such as 
Shift-JIS), it's impossible to cycle back- 
wards through a string. You can’t de- 
termine if any single byte is the first or 
second byte of a multibyte character or 
if it’s a single-byte character. Conse- 
quently, algorithms must be rewritten to 
start at the left and work toward the 
right. But with Unicode (or other fixed- 
size character-code standards), you can 
traverse backwards, saving you from 
having to rewrite code for international 
support. 


Implementing Unicode Support 
A basic technique for implementing Uni- 
code is transparent-character support. 
This is a technique I used to develop 
multiple tape backup applications for 
NT. The goal of the project was to write 
and maintain a single, common set of 
source code such that Unicode would 
be supported if the underlying operat- 
ing system provided sufficient support, 
and any other single-byte character set 
would be supported otherwise. This 
support had to be as portable and trans- 
parent as possible. Code which must 
specifically process strings of a known 
character standard, therefore, had to be 
isolated to a few specific files and code 
sections. 

In order to achieve this goal, the fol- 
lowing conditions had to be met: 


e Transparent characters, macros, and 
functions had to be used. 






~-szlemp); 


Example 1: Splitting off the filename from a pathname. 


for (pszTemp=szFNametstrlen(szFName) -1; 
pszTemp>szFName && *pszTemp != '\\' && 






*psziemp !=':'; 
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® The ProtoGen+ Client/Server 
Suite is a complete visual develop- 
ment environment that features 
multiple database access and 
quality code generation. 


No pain, no gain. 
That's what most client/serv- 
er tool vendors would like 
you to believe. Because 
their 4GL and interpreted 
language tools force you to 
learn proprietary languages 
and lock you into limited 
environments. 

The ProtoGen+ 
Client/Server Suite however, 
harnesses the power and 
robustness of C and C++, 
the world’s most popular 
development languages. 

So Windows developers— 
and former mainframe pro- 
grammers learning 
Windows—can build mis- 
sion-critical client/server 
applications with easy-to- 
use visual tools. 








productivity of 
C and C++. 
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@ The ProtoGen+ Client/Server Suite provides a powerful workbench that lets 
you use point-and-click tools to achieve the exact look and feel you want. 


This visual, integrated 
best-of-breed toolset deliv- 
ers unprecedented speed 
and productivity in an open 
architecture. Including data- 
base access. Forms building. 
Report writing. Application 
management. And quality 
code generation in C, MFC, 


need in todays complex 
client/server environments. 
SO unless you enjoy 
4GL pain, get the Visual 
Development Edge. You have 
everything to gain. 





® Windows 

applications OWL and Pascal. 

built with the Over 100,000 develop- 

eee ers use ProtoView visual 

Client/Server 

Suite deliver tools, including Delta, 
onnesa eo | direct graphical Merrill Lynch, AT&T and 
Whitman otter gm TCCC8S 10 Conrail, for the mission- 
Miller | enterprise SQL ios a 

| databases. critical applications they 


The Visual Development Edge” 
Fax: (908) 329-8624 Outside the U.S., call (908) 329-8588 


All products named are trademarks of their respective companies. ©1994 ProtoView Development 
CIRCLE NO. 432 ON READER SERVICE CARD 





UNICODE 


1. Place all strings that require language translation in your application’s resources. 

2. Declare all text (not binary) data using TCHAR, LPTSTR, LPTCHAR. 

3. Use transparent functions and macros for all TCHAR-type data. 

4. Avoid using ASCII string functions which have no wide-character equivalent. 

5. Check calls to strlen() and multiply by sizeof(TCHAR) if result is used as a byte size. 

6. Ensure all memory allocations for strings are based on byte size, not character count. 

7. Check all transparent-character pointer arithmetic for validity; avoid using characters 
as indexes to 256-element arrays; remember that subtracting two character _ 
pointers yields a byte size, not a character count; always divide or multiply me 
sizeof(TCHAR) to convert between character counts and byte sizes. | i. 

8. Isolate operations on specific character-code standards from transparent code. 

9. Use westombs() and mbstowcs() to convert between Unicode and ASCIVANS|-- 


specific character codes. 


10. Use the byte-order mark whenever processing text files and data streams. | 
11. Define UNICODE macro when compiling transparent modules for Unicode uncon | 
12. Avoid mixing modules compiled to support different default character-code standards. _ 





Figure 1: Guidelines for transparent-character support. 


(continued from page 40) 

e Operations which expect a specific 
byte size had to be avoided or en- 
capsulated. 


I’ve discovered a number of nonobvi- 
ous stumbling blocks in implementing 
transparent-character support, particu- 
larly if you’re converting a non-Unicode 
application to either Unicode or trans- 
parent support. Also, you must consid- 


The 


sible for defining and promoting the 

Unicode character standard. Con- 
sortium members include all the ma- 
jor international computer systems 
providers: Adobe, Apple, Borland, 
DEC, Go, Hewlett Packard, IBM, Lo- 
tus, Vicrosolt Next, Novell, sun, 


Ts Unicode Consortium is respon- 


Symantec, Taligent, Unisys, WordPer- | 


fect, Xerox, and others. 
Unicode derives its name from its 


three main characteristics: universal— _ 
it addresses the needs of world lan- _ 
guages; uniform — it uses fixed-width © 

codes for efficiency; and unique— — 


duplication of character codes is min- 
imized. 
The Unicode Consortium was for- 
mally incorporated in 1991 as a joint 
effort between a number of the major 
computer software and hardware com- 
panies. However, the Unicode stan- 
dard first began at Xerox in 1985 when 
-Huan-mei Liao, Nelson Ng, Dave Op- 
stad, and Lee Collins began working 


on a database to map.the relationships © 


between identical Japanese and Chi- 
nese characters. [his lead to a tech- 

nique called “Han Unification,” which 

Unicode uses to minimize the codes 
it requires. 
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er how to program today for a non- 
Unicode environment, while preparing 
for an eventual migration to Unicode. 
Multibyte character sets may be sup- 
ported as well, but you must employ 
the same localization techniques you 
previously used. Those techniques need 
not be modified; you just follow the sim- 
ple rules outlined here. However, lo- 
calization for multibyte character sets 
may reduce the efficiency of your code. 


Code written following the guidelines 
in Figure 1 will transparently support 
Unicode, ASCII, or any other fixed-size 
character standard for all major lan- 
guages and cultures with only a mini- 
mal localization effort. The basic rule of 
transparent-character support is that the 
size of a character code is determined 
at compile time. If a preprocessor macro 
named UNICODE is defined in your 
compiler’s command-line arguments and 
the platform supports Unicode, your ap- 
plication is compiled to support Uni- 
code. Otherwise your application will 
support any 1-byte character set sup- 
ported by the platform. You need only 
to define another macro and modify 
your header files to support another 2- 
or 4-byte character standard if your plat- 
form provides sufficient support for that 
standard. If you do not compile for Uni- 
code, the particular character standard 
supported is determined by the strings 
contained in your application’s resources 
and the default code page selected by 
the user. This, of course, presumes that 
all strings which require language trans- 
lation are placed in resource files. All 
modules should be compiled with Uni- 
code explicitly enabled or disabled and 


Unicode Consortium 


At the same time, discussions on the 


_ development of a universal character 


set got underway at Apple. In Septem- 


ber of 1987, Joe Becker of the Xerox. 
group and Mark Davis of Apple be- 


gan discussions on multilingual issues had been completed, and — be- | 


with a new type of character encod- 


ing as a major topic. Later that year, — 


Becker coined the term “Unicode” 


working at Apple on Davis’s new char- 


acter-encoding proposals. By Febru- _ 
ary Collins had incorporated the basic 


architecture for Unicode, and Becker 


presented it to a /ust/group interna- _ 
tional subcommittee meeting in Dal- — 
las. Apple decided to incorporate Uni- : 


code support into TrueType. 

In February of 1989, iP anonihhy 
meetings to discuss Unicode began 
between these companies and Sun, 
Adobe, Claris, and the Pacific Rim 


Connections joined in. In addition, 
Glenn Wright of Sun began the uni- 
code@sun.com on Internet for Uni- | 
code discussions. These discussions | 
lead to the decision to incorporate all. 


composite characters in existing ISO 
standards. In 1990, there was a flurry 
of activity, culminating in December, 
when Becker presented Unicode at a 





UN. Talemeonal meeting. Cooper-_ 
ating with Apple on TrueType, Micro- 
soft became interested in Unicode and 
_assigned Asmus Freytag to attend 
- meetings. By March all non-Han work — 


- Meanwhile, Wright saat like Ker- 
i ecelee se | Metaphor started 
The following year saw Collins | 


ae pro- 


cess of incorporating the Unicode 
Consortium, and the work cont ure 
today. . 


Much eHor. hag Been expended to i 


- meet the demands of each language 
represented by Unicode and each 
company and country involved in its 
_ development. International politics 


have often played a significant part in 
the definition of this standard. The re- 
sult is a highly consistent and easily 
usable standard which will be around 
a long time. 
For more information, or to becarne 
a member of the Unicode Consortium, 


contact: Unicode Consortium Inc., 1965 : 
~ Charleston Road, Mountain View, a 


94043. (Phone 415-961-4189, fax 415- 
966-1637, or Internet unicode- me 
.M4.Metaphor.com.) L 


Hee | 
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AVOID EMBARRASSMENT! 


“A customer found a bug in 
our software with a tool 


called BOUNDS-CHECKER... 
Why aren't we using 
BOUNDS-CHECKER?” 





Use BOUNDS-CHECKER™ V2.0 For Windows, The Automatic Bug Finder! 


Whether you're the boss, the QA Manager or the programmer, it's your responsibility to ensure that 
your company's programs for Windows™ are "bug-free" before they get into the hands of customers. 
If you're developing under C or C++, producing a "bug-free" Windows based oroduct is no longer a 


long and stressful experience. 


Announcing BOUNDS-CHECKER V2.0 For 
Windows, the software developer's “safety-net”. 
Quickly and easily eliminate the hardest-to-find 
Windows errors that can take days - even weeks 
to find like: 


e API Parameter Errors 

e AP! Return Value Errors 

e Data and Heap Corruption 

e Resource Leakage Problems 
e Memory Leakage Problems 
e Processor Faults 


HOW IT WORKS — BOUNDS-CHECKER works by 
transparently setting hundreds of breakpoints within 
your program to monitor its behavior. When a bug 
is detected, BOUNDS-CHECKER immediately stops 
your program and pops up showing the problem. 
You can then inspect your program’s source, vari- 
ables, stack and heap ... with BOUNDS-CHECKER’s 
powerful display windows. 

EVENTLOGGING — BOUNDS-CHECKER nowlogs 
all Windows events. Many Windows bugs are diffi- 
cult to find because of the event driven, multi-tasking, mes- 
sage based nature of Windows. BOUNDS-CHECKER V2.0 For 
Windows introduces an event logging and display capability 
that captures all Windows messages, API calls, API! returns 
and other events. The information is displayed in a high-level 
overview that lets you see how your program is interacting 
with Windows. When you want tosee more detail, simply click 
to see a section expanded in great detail. 

EASY TO USE — Unlike other debugging tools, there’s no 
learning curve with BOUNDS-CHECKER. Simply select your 
program's name from BOUNDS-CHECKER’s menu, all the rest 
is Gutomatic. There is nothing to link-in and no macros to 
compile into your program. All this plus the functionality ofa 
heap checker, super spy utility, debug kernel, API debugger, 
and a post mortem tool into a single comprehensive auto- 
matic bug finder. 





Procedure: 
Module: 
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if (iFrame == 8) 
pPal->palVersion = 0: 


week Darameter Validation Error ***** 


anDisplayFrame (001588) 
bituap.obj (bitmap.c line 


: LOCALLOCK returns: 3ADA 
ARPICALL: CREATEPALETTE (PTE: 1 CR?: SADA 
p > CREATEPALBITE returns: 0006 
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Don't Be Left Behind...Develop in Windows NT With Confi- 
dence! Use BOUNDS-CHECKER32/NT, the powerful new de- 
bugging tool specially designed to meet the demands of 
developers using the WIN32 environment. Catch WIN32 bugs 
at their source and ship your products faster! Exclusive Intro- 
ductory offer from Nu-Mega, only $199.00! Call (603) 889- 
2386 to order NOW! 


Call now for overnight delivery. 
BOUNDS-CHECKER V2.0 For Windows... Only $249 
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Order both versions & SAVE $150... Only S298 
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ow that the WIN32 API is the hot- 
N test new topic, and many of you 
are porting applications or writing new 
ones to the WIN32 API, Nu-Mega has a 
new tool that can help you ship solid 
WIN32 applications. It's called BOUNDS- 
CHECKER32/NT,™ an automatic bug 
finding and event logging tool for WIN32 
applications. Our version 1.0 runs on Intel 
based Windows NT platforms. BOUNDS- 
CHECKER32/NT not only detects com- 
mon problems that most C/C++ program- 
mers have encountered in previous ver- 
sions of Windows, but also contains fea- 
tures that help you deal with new problems 
like bugs related to multi-threading. 

For those familiar with BOUNDS- 
CHECKER For Windows you will find 
that BOUNDS-CHECKER32/NT detects 
similar bugs including memory and heap 
corruption, memory and resource leaks, 
bad parameters passed to APIs and un- 
checked errors returned by APIs. When 
BOUNDS-CHECKER32/NT detects bugs, 
it shows detailed information including 
the call stack and the source code. 

The ONLY Event Logger For NT 

With messaging and complex APIs, 
event logging and viewing has become the 
method of choice for finding many types of 
bugs. Now that WIN32 allows multi- 
threaded applications, event logging is 
almost indispensable. Here's how it works? 
As your program runs, BOUNDS- 
CHECKER32/NT traps strategic events 
like messages and API calls, then logs 
them to a trace file. Later, after your pro- 
gram has terminated, BOUNDS- 


CHECKER32/NT displays these events 
in an organized hierarchical display that 
you can easily navigate to better under- 
stand the run-time flow of your program 
or to quickly find bugs. For a more de- 
tailed description, see the November Nu- 
Mega News foradescriptionof BOUNDS- 
CHECKER For Windows event logging 
features. 
Thread Problems 

From our own experience and from 
talking with many WIN3?2 pioneers, we've 
learned that thread related problems are 
some of the most difficult to track down. 
For example, it is typical to have some 
data structures that are shared by multiple 
threads where each thread may have to do 
a series of uninterrupted operations on the 
data before another thread can access the 
data. While designing your application, 
you must identify all of these critical 
sections and provide mutual exclusion. If 
you do not provide mutual exclusion, you 
may end up with an irritating bug that is 
very difficult to track down. 

Although BOUNDS-CHECKER32/ 
NT cannot do the entire job for you, its 
event logging capability can be an im- 
mense help. Each entry in the event log 
contains a thread number field. This lets 
you see how threads actually interacted 
while the program was running. For even 
more clarity, you can highlight a specific 
thread while events from all other threads 
are greyed out. You can also filter out 
specific threads if they are getting in the 
way of your bug quest. 

Another feature that helps with thread 
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related problems is the way BOUNDS- 
CHECKER32/NT shows memory leaks. 
A Leaks window displays information about 
memory and resource leaks including the 
source line and the currently running thread 
when the resource was allocated. 
API Compliance 

We all know how complicated it is 
dealing with the WIN 16 API; under WIN32 
we have three variants: WIN32 NT, 
WIN32S and WIN32C. When you are 
developing under Windows NT but target- 
ing more than one subset, the accidental 
use of a wrong API can easily go unnoticed 
since WIN32 NT is the broadest subset. 
BOUNDS-CHECKER32/NT helps here 
by keeping track of API calls by subset. 
When your program terminates, you can 
bring up BOUNDS-CHECKER32/NT’s 
API Compliance Window to see what APIs 
from each subset were actually used. This 
is especially useful for groups of program- 
mers developing under different subsets or 
when using class libraries that isolate you 
from direct API access. Running 
BOUNDS-CHECKER32/NT on a regular 
basis can eliminate the headaches that will 
appear later on — when you have to re- 
engineer the program because non-con- 
forming APIs were used. 

Conclusion 

When we began designing an auto- 
matic bug detector for WIN32 we decided 
not to simply por. BOUNDS-CHECKER, 
but to build a product from the bottom up 
that met the needs of WIN32 developers. 
We hope BOUNDS-CHECKER32/NT 
meets your needs. 


- Flip & Flap's Puzzler - 


* 
Question: A programmer and a manager decided to compete in the 100 yard dash (for a small wager), The programmer wins by : 
10 yards. The manager says, “double or nothing, but you start 10 yards back.” The programmer says yes. In the 2nd e 

race they both maintain the exact speed as the Ist race. Who wins and by how much? % 

Call, Fax or leave us a message on our BBS with your answer. : 

Answer to January's puzzler: All beanies were black. If one was white, the two wearing black would have immediately e 
® 

® 


known! No Job, because XLAT does not take SI as an argument. See BBS for more... 
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you should avoid mixing modules com- 
piled for different character sizes when- 
ever possible. 

Programs written to support multiple- 
character standards transparently require 
a transparent-character type. Many as- 
sumptions typically made about char- 
acter variables are no longer valid. You 
must take care to ensure that code is 
truly transparent and, if multiplatform 
support is required, portable. The solu- 
tion provided by transparent- character 
support is based on never presuming 
the size of a character. Since a trans- 
parent character may be of any fixed 
size, a new type is used, TCHAR, which 
represents a character of unknown (but 
fixed) size. Other special types include: 


e LPTSTR, a pointer to a NULL-termi- 
nated transparent character string. 

e LPTCHAR, a pointer to a transparent 
character or array. 


Figure 2 provides definitions of these 
types for Unicode and ASCII/ANSI. 

You can’t use the standard C char type 
to store transparent characters, because 
char is the smallest atomic type, which 
is usually a byte. Neither can you use 
the ANSI wehar_t type, since it’s a “wide” 
character type that will always be at least 
two bytes in size— too large for ASCII 
and other single-byte standards. 

Consequently, the first steps per- 
formed when converting your code for 
transparent character support are: 


1. Determine which data elements of 
type char, char *, or any other type 
derived from those are text (and not 
binary) data. 

2. Change all of those to use TCHAR, 
LPTSTR, or LPTCHAR. 


These steps can be trivialized if you 
adapt and rigidly enforce the following 
coding standard early on in your prod- 
uct’s development style: Define a type, 
such as BYTE, and always use that to 
store binary data, and never store any 
nontext data in a TCHAR. In the absence 
of such a standard, these steps can be 
tedious and time consuming. 


Common Problems with 
Pointer Arithmetic 
While most character- pointer arithmetic 
is still valid, a number of widely ac- 
cepted coding practices will no longer 
work when using transparent charac- 
ters. These practices must be avoided 
Or you may experience many wasted 
hours correcting them. 

One of the most common invalid as- 
sumptions is that the length of a string 
plus one is equal to the number of bytes 
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UNICODE 
wehar_¢t 
wehar_t 
wehar_t 


#ifdef 
typedef 
typedef 
typedef 
#else 
typedef 
typedef 
typedef 
#endif 


char 
char 
char 


TCHAR; 
* LPISIR: 
* LPTCHAR: 





// TCHAR's are Unicode 


TCHAR ; 
* LFISIR; 
* LPTCHAR; 


// TCHARS are ASCII/ANSI 





Figure 2: Type definitions for transparent characters. 


required to store it. This can be a par- 
ticularly annoying and sometimes diffi- 
cult problem to deal with when porting 
existing applications. You must learn to 
differentiate between string lengths and 
buffer sizes, or serious programming er- 
rors will result. These errors can be very 
difficult to resolve. 

The next steps are usually easy, but 
can be difficult if a string length is stored 
for later use or passed to other func- 
tions. The steps are: 


e Search for all calls to strlen(), and, if 
the return value is used to determine 
a byte size, multiply by sizeof (TCHAR). 

e Search for all memory-allocation calls 
(malloc, GlobalAlloc, and so on), and 
change those which allocate space for 
characters based on a character count 
to use a byte length. 


Array indexing and general pointer 
arithmetic to determine an offset usual- 
ly work fine, so changes are not nor- 
mally required: *(achPtr+nIndex)= 
chSomeVal;. In this example, the con- 
tents of the mJndexth entry of the array, 
achPtr, would be assigned the correct 
value for any fixed-size character stan- 
dard. As a general rule, whenever deal- 
ing with operations involving transpar- 
ent characters and arrays, simply keep 
in mind that the size of each element 
may be larger than a byte. 

Another common violation is using a 
character as an index into a 256-element 
array. Since a Unicode character is two 
bytes in length, you must either increase 
the size of the array to 65536, or mod- 
ify your algorithm. Also, remember that 
subtracting two pointers yields the num- 
ber of bytes between those pointers, not 
the number of characters. Always mul- 
tiply by sizeof (TCHAR) when calculat- 
ing the byte size of a transparent char- 
acter buffer. Likewise, always divide by 
sizeof (TCHAR) when calculating the 
number of transparent characters which 
can fit in a specified number of bytes. 


Wide-character Functions 

Just as Unicode and transparent char- 
acters required new types, a set of new 
functions is needed to process them. It’s 
critical that, for any function employed 


to process single-byte characters and 
strings, you have an equivalent wide- 
character function. Windows NT and the 
Microsoft C libraries provide a good 
starting set of routines. For the Microsoft 
C library, all wide-character string rou- 
tines utilize one of two simple naming 
conventions to distinguish them from 
standard ASCII variants. In the first 
convention, as specified by the ANSI C 
standard, all ASCII string functions be- 
ginning with str have wide-character 
equivalents which begin with wes. For 
example, the wide-character version of 
strlen is weslen, which, in both cases re- 
turns the number of nonzero characters 
in a string. 

The other naming convention used is 
to identify wide-character functions by 
either prefixing or embedding a w in 
the function name. For example, the 
wide version of printf is wprintf, while 
vswprintf is the wide version of usprinif. 
The header files included with the 
Microsoft C compiler for NT provide a 
complete list of these functions. The 
Microsoft Win32 API uses a different 
naming convention to distinguish ASCII 
and wide-character variants of the API 
procedures. All ASCII/ANSI versions of 
the Win32 API end with the letter “A.” 
Similarly, all Unicode (or wide) versions 
end with a “W.” Therefore, CreateWin- 
dowA expects 1-byte characters, while 
CreateWindowW expects Unicode char- 
acters. This is an excellent naming 
convention in that it is easy both to re- 
member the name of any character- 
specific routine, and to identify all 
character-specific (that is, nontranspar- 
ent) code at a glance. 


Transparent-character Macros 

What makes the Win32 naming con- 
vention particularly appealing is that, 
with only a few exceptions, whenever 
you use a Win32 API procedure with- 
out an A or a W suffix— that is, when 
you use the same name as the one used 
for Windows 3 applications— you are, 
by default, supporting transparent char- 
acters. Consequently, code modifications 
to Windows API procedures usually 
aren't required to globalize an existing 
application. The exceptions are those 
Win32 API file procedures considered 
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obsolete but provided for backwards 
compatibility to Windows 3; OpenFile 
and _lopen, for example. Consequent- 
ly, you must use the Win32 CreateFile 
family of functions to support Unicode 
filenames. For C library functions, how- 
ever, things aren’t so easy. The Win32 
naming convention replaces wes with 
tcs and the prefixed or embedded w 
with ¢to create transparent equivalents. 
To convert your code for transparent- 
character support, therefore, you must 
replace all calls to these string functions 
to use the transparent name instead. This 
usually entails a great deal of work. 
There is an alternate method which 
requires less work for most existing ap- 
plications. Instead of modifying the 
source code, you create a header file, 
which maps the standard string function 
names to the wide-character equivalents 
when compiling for Unicode, as in Ex- 
ample 2. By doing this for each standard 
string function used in your code, you 
can often reduce the number of changes 
required. However, this technique ef- 
fectively removes all of the standard char- 
acter functions when you compile for 
Unicode. If you need to process ASCII 
data, you'll have to write your own 
ASCII-specific replacements. For each of 
these functions — including all those 
which use filenames, atoi(), and some 
others— you must implement the wide 
version yourself, or avoid using them. 


Mixing and Converting 

Character Standards 

There are times when code must be 
written to support multiple character 
standards, either for backwards com- 
patibility or for transferring data between 
platforms. Care must be taken when 
mixing transparent coding techniques 
with character-specific data types, or the 
resulting code will be very difficult to 
maintain. 

Code that supports a specific charac- 
ter type is not transparent and should 
be isolated from transparent code, 
preferably by placing the code in a sep- 
arate function. One method of handling 
this is to create two versions of your 
function— one that accepts Unicode 
strings and another for ASCII strings — 
along with a transparent mapping 
macro, as described earlier. An alternate 
method is to write a single function that 
takes and returns transparent characters. 







#ifdef UNICODE 

#define strlen wceslen 
#define sprintt swprintt 
#endif 







Example 2: Portion of header file 
which maps the standard string 
function names to the wide-character 
equivalents. 
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. pszXparent, int cchMaxBuf ) 


| return, 


Example 3: Converting between transparent and ASCII characters. 


On entry to this function, the TCHAR 
parameters are converted to the required 
character standard and processed. Any 
resulting characters are then converted 
back to TCHAR, and the function re- 
turns; see Example 3. 

Also, notice how the routines use the 
standard ANSI C functions westombs and 
mbstowcs, which convert single- or 
multibyte strings to wide-character 
strings and vice versa, using the current 
code page for the multibyte string. Keep 
in mind that a Unicode string convert- 
ed using wcstombs may contain multi- 
byte characters, which can complicate 
processing. 


Reading and Writing 

Unicode Text Files 

Unicode contains a special character 
code, called the “byte-order mark,” 
which has a value of Oxfeff and is used 
to identify a text file or data stream as 
a collection of Unicode characters. It is 
important to use this mark whenever 
reading or writing text files. Additionally, 
this mark provides the information nec- 
essary to transfer data between Big- and 
Little-endian systems. Whenever a Uni- 
code text file is created, or a stream of 
Unicode text is passed to another ap- 
plication or system, it is important to en- 
sure that the first character written is the 
byte-order mark. Likewise, whenever 
you open a text file, or receive a stream 
of text, you should check for this mark. 
Then, you will need to convert the text 
as it is read to transparent characters be- 
fore your application can use it. For this 
reason, you should encapsulate all file 
operations in a simple API. 

The byte-order mark value was cho- 
sen because the possibility of Oxfeff oc- 
curring in the first two bytes of any non- 
Unicode text stream is highly unlikely. 
Also, its mirror image, Oxfffe, which is 
not a Unicode character, provides use- 





ful information for transferring data be- 
tween Big- and Little-endian systems, 
since their byte orders are reversed. 
Therefore, if a text stream starts with 
Oxfffe, there is a good chance that it 
contains byte-swapped Unicode text, so 
you will need to reverse the byte order 
of each character as it is read. 


The Future of Unicode 

The Unicode standard is still new and 
not yet complete. The few issues that 
remain to be resolved will not signifi- 
cantly affect the development of trans- 
parent code. However, another char- 
acter standard which defines a superset 
of the Unicode standard is under de- 
velopment—ISO 10646. Fortunately, 
applications developed to meet the 
guidelines presented in this article will 
require little or no modification to sup- 
port this standard as well. ISO 10646 
comes in two flavors: two-byte charac- 
ters, which are essentially the same as 
Unicode, and 4-byte characters, which 
will eventually represent every charac- 
ter used in every known language. 
However, it’s doubtful that ISO 10646 
will ever become a common standard; 
it will likely be limited to special- 
purpose systems. 

Unicode will probably become the 
predominant standard for all future sys- 
tems. Unicode systems are currently un- 
der development by Microsoft, Apple, 
Novell, Next, Taligent, Metaphor, and 
others. By using transparent-character 
support in your applications, you will 
be able to exploit the benefits of these 
systems as they become available and 
quickly enter new language markets 
with a minimum of effort, while main- 
taining compatibility with current sys- 
tems and standards. 
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Kmulating 


Non-DOS Systems 
Under MS-DOS 





Creating a development 
environment for working 
within the familiar 
confines of DOS 





Dan Troy 


ne of the challenges embedded- 
systems designers have grappled 
with for years is developing for 
operating systems that require 





matters, we also needed to develop a 





Realizing this, we wanted to create 
a development environment for the 
VP5 that would allow programmers to 
work within the familiar confines of 
MS-DOS using DOS-based tools. Fur- 
thermore, we wanted programmers to 
test applications under MS-DOS be- 
fore loading the cross-compiled pro- 
gram into the VP5. Just to complicate 


unfamiliar, nonstandard development | 


tools. Coincidentally, this is the prob- 
lem that is now confronting many pro- 
grammers writing software for the 
emerging class of hand-held, wireless, 
personal-data communications devices 


such as the Newton MessagePad from | : 
Apple, Zoomer from Casio, and, in this | 


case, my company’s VP5 personal dig- 


ital-communication device. Still, his: 
Figure 1: Non-DOS VP5 handheld 


tory has taught us that: 


e No matter how slick it is, a hardware 
device won’t be accepted by users if 
there’s no software for it. 

e Programmers won't write software for 
a hardware device unless the devel- 
opment environment is at least ap- 
proachable. 


Dan is a software engineer at Granite 
Communications Inc., 9 Townsend 
West, Nashua, NH 03063. He can be 
reached at 603-881-8666, or by fax at 
603-881-4042. 
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ist. Also, since the emulation code is 
written in ANSI C, it is portable to any 
other microprocessor/operating-system 
environment, as long as the necessary 
hooks exist between the development 
platform and the remote communica- 
tion device. In addition to this, con- 
tained in the emulation code is the sim- 
ple, table-driven function-execution 
mechanism, which is applicable to any 
other remote-execution environment 


The VP5 is a wireless, hand-held, 
touchscreen personal data communi- 
cator (see Figure 1) designed to allow 
VARs and programmers to develop 
custom touchscreen applications writ- 
ten in C. To emulate as many video- 
pad functions as possible — including 
the touchscreen and display— we de- 


_ cided to remotely execute the propri- 


etary videopad operating-system func- 


F tions from MS-DOS on the PC. The 





device. 


simple mechanism for adding new 
operating-system function-emulation 
capability as existing products are en- 
hanced, or as new products are devel- 
oped. This article presents the solution 
we devised for the VP5 development 
environment. 

Our approach to remotely execut- 
ing an application isn’t specific to the 
VP5, however. You should be able to 
apply it to any similar situation where 
noncompatible operating systems ex- 





7 developer could then see the VP5 


screen exactly as it appears when the 
application is cross-compiled, linked, 
loaded, and executed in the VP5 it- 
self. Also, the developer could actu- 
ate developer-defined, touchscreen- 
sensitive keys to make sure the 
application did what it was expected 
to do. This gives WYSIWYG feedback 
in the development process. To ac- 
complish this goal, we remotely com- 
manded the VP5 via the serial ports 
on the PC and VP5. In order to allow 
easy emulation expandability for fu- 
ture enhancements and portability to 
new products, we developed a table- 
mapping mechanism that would han- 
dle C operating-system functions and 
their associated parameters. 
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EMULATION 


VP5 pri edad function call on PC 


VP5 Jeet in a library 


_VP5 function on PC sends command ig this function to VP5 via RS-232 port 


Special application on VP5 receives command for this function 


Seer application on ee executes this function 


Teck application on VP5 returns any ees from function call back to PC 


-VP5 function i in ae on n PC returns any os to actual application function call 





Figure 2: Flow of control in VP5 emulation environment. 


(continued from page 52) 

The overall emulation logic is sum- 
med up in Figure 2. To implement all 
89 videopad operating-system calls, 
we implemented a table- driven mech- 
anism. The table is defined as an ar- 
ray of structures of type shown in List- 
ing One (page 58). Listing Two (page 
58) shows a portion of the table. Ac- 
cording to the table, the inputs to the 
define_key() function are character, in- 


Our approach to 
remotely executing 
an application isn’t 

specific to the 

VP5—you should 
be able to apply it 

to any similar 
situation where 
noncompatible 
operating systems 
exist 


teger, character, character, character, 
character, character, string. There are 
no outputs (NULL string). This corre- 
sponds to the function prototype in 
Listing Three (page 58). The execution 
sequence to remotely define a key on 
the VP5 keyboard would be like that 
in Listing Four (page 58). 

On the PC side, the VP5 operating- 
system library function looks like List- 
ing Five (page 58) which calls pro- 
cess_cmd(); see Listing Six (page 58). 
This, in turn, sets up and sends a mes- 


sage to the special VP5 emulation ap- 
plication and receives the response from 
the VP5. 

The counterpart of the define_key() 
function resides on the VP5. It uses 
the arg_table[/ identical to that on the 
PC-emulation software. Listing Seven 
(page 60) is the VP5 emulation-command 
processor. 

The spawn_define_key() function is 
a spawned function located in the 
arg_table[], see Listing Eight (page 62). 
No return values must be passed to 
the define_key() function in the cus- 
tomer application. However, in get_ 
key(), the videopad must return the 
key value pressed on the videopad. In 
this case, the VP5 operating-system li- 
brary function looks like Listing Nine 
(page 62). 

Since the get_key() function has no 
inputs, none are required to set up 
the call to process_cmd(). The actu- 
al key pressed on the videopad is in 
c[1]. But why are there two outputs — 
c[O/ and c/1/—in the get_key() table 
entry, when there’s only one output 
from get_key()? Because in this case, 
get_key() on the videopad will wait 
forever for a key to be pressed under 
normal operation. If the application- 
program developer decides to take his 
or her time pressing a key after get_ 
key() has been called, then the emu- 
lation software on the PC will even- 
tually time out. To avoid this and 
allow the developer to spend as much 
time as he or she desires before press- 
ing a key on the videopad, we im- 
plemented the algorithm in Listing Ten 
(page 62) on the VPS. Here, the 
spawned function spawn_get_key() 
is found in the arg_table[/. If no key 
has been pressed, the function im- 
mediately returns a False condition 
for c/O/. The emulated get_key() func- 
tion on the PC loops until a key is 
pressed, thus maintaining constant 
communication between the PC and 
the VP5. 

(continued on page 57) 
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Breakp 





(p_char, p_int, p_char_poi 
p_char; 
pint; 
*p_char_pointer; 





simO40f 


-hex- 
ooooc000 
ooo00002 
ooo000004 
oooo0006 
00000008 
oooo000A 





struct_t t_struct; 
static stat; 
extern varl: 
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(continued from page 54) 
One drawback of executing the ap- p4 Identical to serial-port connector on VP5 
plication remotely is that the VP5 RS- 
232 port is not available for the appli- 
cation since it’s being used by the 
emulator. In order to emulate the VP5 | COM2 = 
RS-232 COM serial- port communications Einhorn sl ere PC used to emulate application | 
within the emulated application, the Jo ” 
other RS-232 port on the PC, COM2, is 
used. In other words, data that would 
normally be transferred on the VP5 
COM port is instead transferred via 
COM2 on the PC, since the VP5 COM 
port is being used for application em- 
ulation. We created a special cable so 
that the VP5 COM port is now repre- 
sented by p4 (see Figure 3). The p4 
connector is the same as the COM port 
ea thes. ee 


We decided to 
remotely execute the 
proprietary 
videopad operating- 
system functions 
from MS-DOS on 
the PC 








A Sample Program 

Listing Eleven (page 62) is a typical 
VP5 program in which the touch-sen- 
sitive, boxed key appears on the VP5 . en, 
and the VP5 waits until the defined fa\e 
key is pressed. When the defined key 
is activated by the user touchscreen, 
the screen clears, and the message dis- 
played in the WELCOME_KEY is re- 
placed with the “Requesting Info” mes- 
sage. The VP5 then logs on to the base 
station, sends a message to the host, 
and waits until a message is received : we a 
back from the host. Then the received * : | an 
message is displayed in the defined . ) 
text window on the VP5 screen for ten | | BUIL 
seconds. This sample program can be | | di 
tested under CodeView, utilizing its BOOTS FRO 

full functionality and incorporating | | : 

DOS calls such as printf) while de- | | -SQURCE CODE AVA 
bugging. | , 
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(Listings begin on page 58.) z cea OTABLE DEM 
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Listing One (Text begins on page 52.) 


EMULATION 


Listing Five 


void define_key(char key_name, int key_attributes, char 


typedef struct args 

{ start_row, char start_col, char end_row, char end_col, 

unsigned char *input; /* string of inputs to function */ char font_table, char *key_label) 
unsigned char *output; /* string of outputs from function */ 
void (*spawn_function) (); /* emulated VP5 OS function */ 

uy 


key_name; 

key_attributes; 

start_row; 

start_col; 

end_row; 

end_col; 

font_table; 

const struct args arg_table[] = strepy(s[@], key_label) ; 

{ cmd = DEFINE_KEY; 
process_cmd(); 


Listing Two 


/* COMMAND RESPONSE SPAWN COMMAND */ } 
/* — ARGS ARGS FUNCTION OFFSET */ 
° e e 
or Listing Six 
*/ 
*/ void process_cmd (void) 
*/ { 
*/ 
*/ 
*/ ; 
*/ /* frame up command to send to videopad */ 
7 ib spawn_turn_off, /* 8 */ while(element_type = arg_table[cmd] .input [element++] ) 
ae wa spawn_wait_1_sec, /* 9 */ { 
#3 switch (element_type) 
{ 
* ae /* argument type of character */ 
Listing Three /* pack it into global cmd_buff via pack_char() 
case 'c': pack_char(c[c_entt+]) ; 
void define_key(char key_name, int key_attributes, char emd_buff_length++; 
start_row, char start_col, char end_row, char end_col, break; 
char font_table, char *key_label). /* argument type of string */ 
/* pack it into global cmd_buff via pack_char() 
e e ! !. = . 
Listing Four case 's!; ee Q; 
{ 


Nereceoes™,. spawn_define_key, /* 
Nea", ae spawn_display_key_label, /* 
"eee", wae spawn_display_window, /* 
sa Nea"; Spawn_get_key, /* 
te" Non, spawn_rf_close, /* 
"eie", Mec, spawn_rf_open, /* 
my, "cis", spawn_rf_read, /* 
"Te", ue spawn_rf_write, /* 


OANADAUFP WHE DQ 


#define WELCOME_KEY 'W' temp_char = s[s_cnt] [str_lengtht+] ; 


pack_char (temp_char) ; 


: while (temp_char) ; 
define_key (WELCOME_KEY, BOX|SENSITIVE, 'A' s_cnttt; 


STANDARD_FONT, emd_buff_length += str_length; 
"WELCOME to GRANITE'S VP5\nPRESS HERE to BEGIN"); break; 


(continued on page 60) 
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Listing Six (Listing continued, text begins on page 52.) Listing Seven 


/* argument type of integer */ void main (void) 

/* pack it into global cmd_buff via pack_char() */ 

case 'i': pack_char((char) (i[i_cnt] >> 8)); int status; 
pack_char ((char) (i[i_cntt++] & Oxff)); init_link_layer(); 


emd_buff_length += 2; for (33) 
{ 


break; 
} 
} 
/* send framed up function command to videopad */ 
if (link_layer_send(cmd_buff, cmd_buff_length) != 
TX_OK) process_fatal_error (NO_LINK_RESPONSE) ; 
/* look for link layer response from videopad - time out 
if none is found within expected time */ 
while((rx_status = link_layer_received()) != READY |} 
rx_status != TIMED_OUT); 
if(rx_status == TIMED_OUT) process_fatal_error (TIMED_OUT) ; 
/* process response from videopad */ 


/* if first byte of response buffer (status) is 
not a status command character, then process error */ 
if (response_buff[@] != RESPONSE_STATUS_COMMAND) 
process_fatal_error (NON_STATUS_RETURNED) ; 
while(element_type = (arg_table[cmd] . output [element++] ) ) 


switch(element_type) 


/* argument of type character */ 
/* unpack it and put into global c[] array */ 
case 'c': c[c_entt+] = unpack_char(); 
break; 
/* argument of type string */ 
/* unpack it and put into global s[][] array */ 
case 's': str_length = 9; 
while(((s[s_cnt] [str_lengtht++] = 
unpack_char()) != 0) && (str_length <= 
MAX_STRING_SIZE) ) ; 
break; 
/* argument of type integer */ 
/* unpack it and put into global i[] array */ 
case 'i': il[i_cnt] = (int) (umpack_char() << 8); 
ifi_ent] |= (int) unpack_char () ; 
break; 






DOS Developers Survey: 





‘CINo! 


DDJ394 


| don't want to find out how | can save a lot of money using ROM-DOS 5 instead of MS-DOS® 
in our 80x86 product line. | don't care if ROM-DOS 5 is compatible with MS-DOS 5 but costs 
much less, | like spending much more than | have to. It makes me feel like a philanthropist 


/* look for link layer command from PC - time out if 
none is found within expected time */ 
while((rx_status = link_layer_received()) != READY }| 
rx_status != TIMED_OUT); 
if(rx_status == TIMED_OUT) 
process_fatal_error (TIMED_OUT) ; 
/* process command from PC */ 
/* first byte of command message is command */ 
emd = cmd_buff[@] ; 
while(element_type = (arg_table[cmd] . input [element++] ) ) 
{ 


switch(element_type) 
{ 


/* argument type character */ 
/* unpack it and put into global c[] array */ 
case 'c': c[c_cnt+t+] = unpack_char(); 
break; 
/* argument type string */ 
/* unpack it and put into global s[][] array */ 
case 's': str_length = @; 
while(((s[s_cnt] [str_lengtht+] = 
unpack_char()) != 0) && (str_length 
<= MAX_STRING_SIZE)); 
break; 
/* argument type integer */ 
/* unpack it and put into global i[] array */ 
case 'i': if[i_ent] = (int) (unpack_char() << 8); 
ifi_ent] {= (int) unpack_char (); 
break; 
; 
} 
/* look up spawning function corresponding to cmd */ 
function_address = arg_table[cmd] .spawn_function; 
/* execute spawning function */ 
(*function_address) (); 
/* prepare response message to last received cmd */ 
response_buff[@] = STATUS_OK; 


/* frame up command to send to videopad */ 
while(element_type = arg_table[cmd] . input [element++] ) 
{ 


switch (element_type) 
{ 


/* argument type of character */ 





(continued on page 62) 





and besides Microsoft probably needs the money more than | do anyway. 


| want to know the facts about ROM-DOS 5. Please send me « 
| | Yes y information and a free bootable demo disk to try with my software. Plant a tree.... 


Trees for America” 


























Name 
Company Join me and plant a tree. Trees 
y for America...and for the earth. For 
ae your free brochure, write: 
City States Zip Trees for 
America 
Phone Fax 
The National 
CPU Product Type Arbor Day 


Foundation, 
Nebraska 
City, NE 
68410. 


Est. Production Date ____EEs—CSCSCSCS st. Arnal Qty. 


In the U.S.A. Call Toll Free 1-800-221-6630 
307 N. OLYMPIC, SUITE 201 * ARLINGTON, WA 98223 USA « (206) 435-8086 ° FAX: (206) 435-0253 


Datalight: 


L. ee ee ee es es es ss V'S-D05 and Microsoft are registered trademarks of Microsoft Corporation Hi J 
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EMULATION 


Listing Seven (Listing continued, text begins on page 52.) 


/* pack it into global response_buff via 
pack_char() */ 
case 'c': pack_char(c[c_entt+]) ; 
response_buff_lengtht+; 
break; 
/* argument type of string */ 
/* pack it into global response_buff via 
pack_char() */ 
case 's': str_length = @; 
do 
{ 
temp_char = s[s_cnt] [str_length++] ; 
pack_char (temp_char) ; 


while (temp_char) ; 
s_cntt+; 
response_buff_length += str_length; 
break; 

/* argument type of integer */ 

/* pack it into global response_buff via 

pack_char() */ 

case 'i': pack_char((char) (i[i_ent] >> 8)); 
pack_char((char) (i[i_entt+] & Oxff)); 
response_buff_length += 2; 
break; 


} 
/* send framed up function command to videopad */ 
if (link_layer_send(response_buff, 


response_buff_length) != 
TX_OK) process_fatal_error (LINK_ERROR) ; 


Listing Eight 
void spawn_define_key (void) 
{ 


define_key(c[@], i[@], c[1], ¢[2], c[3], cf4], c[5], s[0]); 
} 
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GREP (MULTI-BUFFER OR FILE SEARCH) 


Instantly view a pop-up list of all matches in either the current buffer, all buffers, 
or even a group of files. For each file name, the list of matches and their line 
numbers follow. Simply point and shoot to jump to a match! 


MULTIPLE KEYSTROKE MACROS 


Now assign keystroke macros to any key! Keep them around for the current 
editing session or make them a permanent addition to your BRIEF environment. 


MULTIPLE SCRAP BUFFERS 


Finally you have a history of your last 5 scrap buffers! Instantly pop up the scrap 
buffer list and choose a buffer to insert. You can even EDIT your scrap buffers! 


GLOSSARY 


Now you can save frequently used blocks of text (even columns) to reuse later. 
Then just type the glossary name and press a key— EditMaster instantly replaces 
the name with your saved text block. 


TEMPLATES WITH AUTOFILL 


Define your own templates, such as comment blocks, function and file headers. 
EditMaster automatically expands glossary entries inside your template. Your 
cursor is placed at the position you define. Templating makes your code 
uniform and saves valuable programming time. 


JY COMPREHENSIVE 50-PAGE USER’S MANUAL INCLUDED 
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® e e 
Listing Nine 
char get_key (void) 
{ 
do 
{ 
cmd = GET_KEY; 
process_cmd(); 
Jwhile(!c[@]); 


/* return actual key pressed on videopad here */ 
return(c[1]); 


) e 
Listing Ten 
void spawn_get_key (void) 
{ 
if (key_pressed()) 
{ 


c [@] 
e[1] 


TRUE; 
get_key(); 


} 
else c[@] = c[i] = FALSE; 


Listing Eleven 


/* special vp5 library header files */ 
#include <key.h> 

#include <times.h> 

#include <control.h> 

#include <rf.h> 

#include <display.h> 


#define WELCOME_KEY 'W' 
#define BASE_STATION_NUMBER 7 
#define PERIOD 30 


char *msg_to_send = "Please send me the info"; 
unsigned int unsol_size; 


unsigned char unsol_msg [2048] ; 
void main (void) 


unsigned char key; 
int i: 
unsigned char remote_number; 
unsigned int msg_length; 
/* define a boxed, touch sensitive key on rows A and B of 
the VP5 screen */ 
define_key (WELCOME_KEY, BOX|}SENSITIVE, 'A', '1', 'B', '8', 
STANDARD_FONT, "WELCOME to GRANITE'S VP5\n" 

"PRESS HERE to BEGIN") ; 
/* wait until a sensitive VP5 key is touched */ 
key = get_key(); 
/* replace message in WELCOME_KEY with a new message */ 
display_key_label (WELCOME_KEY, "Requesting Info\n" 

"Waiting for response") ; 
/* log on to base station via RF */ 
rf_open(BASE_STATION_NUMBER, PERIOD, unsol_msg, 

&unsol_size, unsol_handler, &remote_number) ; 
/* send the message via RF to the host */ 
rf_write(strlen(msg_to_send), msg_to_send) ; 
/* wait for the response from the host */ 
rf_read(&msg_length, msg_revd) ; 
/* display response from host on VP5 screen from line 3 
through line 12 */ 

display_window(TEXT_WINDOW, 3, 12); 
for(i = 0; i < msg_length; i++) display_char(msg_rcvd[i]); 
/* log off the base station via RF * 
rf_close(BASE_STATION_NUMBER) ; 
wait_1_sec (19) ; /* display revd msg for 10 seconds */ 
turn_off(); /* shut off VP5 */ 


End Listings 
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Great Minds Get Together... 


at Software Development ’94 in San Jose. 
Microsoft will be there. Will you? 
































What motivates some of the world’s most accomplished software professionals to gather under one roof at 
SD’94? Without question, the opportunity to widen their technical horizons, to generate new ideas for the future, 
and to spark the imagination in an environment of pure innovation. 

These are the reasons why the industry’s best join Microsoft. No company has advanced software as 
dramatically as we have, or continues to drive the pace of change as fast in the areas of intelligent home and office 
devices, portable and hand held devices, new system software and tools, wireless communications, advanced 
interactive technologies, on-line services, entertainment and children’s software. 


Come and meet with our Development Managers at SD’94 and talk candidly about how you can impact the future 
of software development in one of these roles: 


Software Design Engineers 


You will be involved with all phases of development, working with small dedicated teams of world-class Software 
Engineers designing new and sophisticated Microsoft products and establishing the future of personal computing. 
Requirements include a minimum of 3 years programming in C/C++ in the microcomputer environment and 
knowledge of Windows programming. 


Software Design Engineers in Test 


You will be intimately involved with all aspects of the development process, designing, implementing and executing 
tests for Microsoft products and writing test documentation. You’ll become an expert on the internals of the 
products as you design and code sophisticated software that exercises new system architectures to ensure product 
completeness and testability. Requirements include a minimum of 2 years programming in C and previous 
testing/quality assurance experience. 


Technical Program Managers 


You will be the product’s technical catalyst, owning the development from inception to release. You will write the 
product specifications and make feature trade-offs, driving all aspects of development from implementation and 
testing through marketing and delivery of the latest Microsoft products. Requirements include a minimum of 2 years 
software development and product management experience. 


Opportunity awaits. Make it happen. 
It’s all happening just a few minutes outside of Seattle, where the air is clean and the lifestyle is upscale and 
affordable. Send us your resume and salary history. We’ll get back to qualified individuals with all the details of our 
visit to SD’94. Send your resume to: MICROSOFT CORPORATION, Attn: Recruiting, Dept. A2872-0394, One 
Microsoft Way, Redmond, WA 98052-6399. If you can’t make it to SD’94, we still want to hear from you. Please indi- 
cate on your cover sheet that you won’t be attending. NO PHONE CALLS PLEASE. We are an equal 


opportunity employer and support workforce diversity. 


Microsoft 














Cross-Platform Development 








A familiar API for UNIX, 
Windows, and more 





Chane Cullens 


he current crop of hardware archi- 
tectures and operating environments, 
each with its own particular set of 
features, offers exciting possibilities 
for software developers. However, time- 
ly development of applications that take 


advantage of the unique capabilities of — 


platforms ranging from DOS, Windows 
3.1, the upcoming Windows 4.0, and NT, 


to OS/2, UNIX, and Macintosh can bea 


challenging undertaking. Toss new CPUs 
such as the Pentium and PowerPC into 


the ring, and you’re faced with some se- =~ 


rious development decisions. 





with Visual C++ 


compile Visual C++ code so that it runs 
as an X/Motif app on UNIX. The Mirrors 
toolkit from Micrografx, on the other 
hand, lets you recompile Windows code 
generated by Microsoft C 6.x or Watcom 
C++ 16-bit for OS/2 applications. Like- 
wise Microsoft's Wings, an announced — 
yet unreleased — toolkit based on the 
Win32 API will someday allow you to 
port Windows applications to the Mac- 
intosh. (Wings will likely include the 
Microsoft Foundation classes, associat- 
ed libraries, code generator, and cross- 


compiler to the 680x0 architecture.) 





i wt 
i 
ee 


The most common approach to tack- Sees 


ling such challenges includes using cross- 
platform APIs (such as XVT, Neuron 
Data Open Interface, and Visix Galaxy) 


or cross-platform application frameworks = 


(Inmark’s zApp, C++/Views, and the Zinc 
Framework, for example). These tools 
can solve most of your portability prob- 


lems, but programmers often end up ~ 


wanting a familiar API that’s available 
across a wide variety of operating envi- 
ronments and hardware architectures. 
Of all the available programming in- 
terfaces, the Microsoft Windows API has 
become the most pervasive. Further- 
more, one of the benefits of using the 
Windows API is that a large number of 
high-quality tools and class libraries are 
available, including those that enable 
you to maintain a single set of source 
code for different platforms. For exam- 
ple, with Wind/U from Bristol Technol- 
ogy (the company I work for), you re- 


Chane works with Wind/U at Bristol 
Technology and can be reached at 
chane@bristol.com or 203-438-6969. 
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Although generally regarded as a 
DOS/Windows development tool, Mi- 
crosoft’s Visual C++ and the Microsoft 
Foundation Class (MFC) library can be 
used as a cross-platform development 
tool. This article discusses how you can 
use Visual C++/MFC as the cornerstone 
of your cross-platform development ef- 
forts. If you write code applying the 
guidelines presented here, you can more 
easily cross architectural hurdles when 
using cross-platform APIs, cross-plat- 
form frameworks, or current and future 
portability toolkits. 

There are several technical reasons 
for choosing the Windows API over Mo- 
tif, particularly for UNIX applications. 
Even without considering portability, 









Windows offers much richer GUI com- 
ponents and paradigms. The typical Mo- 
tif application is about as sophisticated 
as Windows 1.0 programs were. Most 
applications don’t print CX/Motif has no 
built-in printing model), provide online 
help, use tool/status bars, do much in 
the way of graphical drawing, or cleanly 
support multiple documents (there’s no 
MDI in Motif). In other words, portabi- 
lity is only one reason why UNIX de- 
velopers should consider the Windows 
API as a development environment. 


Portability Pitfalls 
Simply choosing a cross-platform class 
library or API does not solve all the 
portability problems involved in writing 
an application. You must also consider 
compiler differences, API nuances, and 
hardware-architecture dependencies. 
In general, UNIX compilers are based 
on the AT&T cfront implementation, and 
PC compilers are implemented to be 
cfront 3.0 compatible. Visual C++ is very 
compatible with the UNIX C++ 3.0 com- 
pilers supplied by HP, IBM, and Sun, 
but not identical. One sure way to min- 


« imize the differences is to compile with 


verbose warning messages on all archi- 
tectures and update the source code to 
remove these warnings. The following 
figures identify some minor differences 
between compilers and easy work- 
arounds to remove the problems. 

Figure 1, for instance, shows how Vi- 
sual C++ allows typecasting using func- 
tion-call syntax. cfront compilers only 
support the C syntax for typecasting 
(more on typecasting in the following 
sections). 

Visual C++ allows type int and user- 
defined type BOOL to be interchanged. 
With other platforms, user-defined types 
may be defined slightly differently. Con- 
sistent use of the user-defined types will 
avoid any problems; see Figure 2. 

In Figure 3, Visual C++ allows variable 
declaration in switch statement cases 
without requiring a new scope. Like- 

(continued on page 08) 
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Monday - The assignment Tuesday - Use C++/Views” visual interface builder 











“OH, NO! I agreed to get this application built by Friday... “Hey, ’'m already ahead of schedule. I’ve got my dialogs 
on Windows, Motif and the Mac.” laid out - I just have to finish the menus.” 


Wednesday - Use C++/Browse™ Thursday - Finish MS° Windows” version 
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“Now, I'll use the class browser to create my classes 


“Yess-ss!” 
and attach them to the dialogs and menus.” 
Friday - Porting frenzy 


OSE/Motif OS/2” Macintosh* DOS Text 


“I had some extra time, so I put it on OS/2 and DOS too.” 


How to build applications on an insane 
schedule without going crazy. 








Shock everyone (including yourself), and get your GUI develop- —_ design gives you object-oriented programming power and flexibility, 
ment done quickly and portably. Simply use C+ +/Views 3.0, the best without sacrificing platform-specific features, performance, or native 
visual programming tool for multi-platform development. look-and-feel. 

C++/Views 3.0 includes a new visual interface builder with Call us today for more information and a free white paper. 

owerful features such as callback editing, geometry, and portable 
sere a Call 800-237-1873. Fax 508-820-0035. 

Its browsing utility lets you create, derive, and edit C++ classes In Europe, call (44) 71-799-2434. Pax (44) 71-79-2552. 
interactively. And it automatically keeps your source, header, and make CIRCLE NO. 365 ON READER SERVICE CARD 
files synchronized. 

Its class library provides an comprehensive set of GUI, extended | A | \ 

GUI, data, and file management classes. Best of all, C+ +/Views unique 


All trademarks belong to their respective companies. Copyright © 1993 Liant Software Corporation, 959 Concord St., Framingham, MA 01701. Phone 508-872-8700 







































ven a free memory manager may not be a bargain—especially if 
it can’t give you all the memory you need. 


Introducing QEMM7 
The Memory Manager Worth Paying For 


The newest version of the Quarterdeck Expanded Memory Manager 
(QEMM) version 7 once again is extremely innovative in using the 
critical area between 640K and 1024K. It finds space for more TSRs 
and drivers in this area than anyone thought possible. It optimizes this 
area, taking into account the many drivers that need more memory at 
start-up than when running; instantly calculating millions of possible 
memory configurations to find still more memory for your programs 
to use. And it treats the rest of memory as a giant pool to instantly 
fulfill the needs of all of your programs—whether they use extended 
or expanded memory. Whether your PC has 1 megabyte or 16, you can 
benefit from new QEMM 7 


Instant Riches 


What does more memory mean in a practical sense? It means that 
your DOS and MS Windows programs run 
faster, smoother and more reliably. It means 
you can continue to add valuable utilities, 
drivers, TSRs and new capabilities to your 
PC. Whether its workhorse drivers like 
LAN utilities and fax drivers; productivity- : 
enhancers like disk caches and disk compressors; cr 
or fun and exciting capabilities like sound boards, CD ROM drivers, 
graphics tablets, etc. The better your memory is managed, the more 
versatility and flexibility your PC has. Q9EMM 7 lets you have it all 
without fear of ‘out of memory’ messages or crashes. 















The key to Stealth is its use of a There’s lots more to QEMM 7: 















| | 64K reserved area above 640K called ¢ Tuned for MS Windows 
aes the page frame. Besides being used by _| * New ability to use Vidram inside 
SS S Windows 
Stealth, the page frame is used by © DPMI Host 
_wewas ar Sii Lotus 1-2-3 r2.x for larger spread- ¢ Pentium Support 
* ~  sheets and WordPerfect 5x for larger | * Laptop suspend/resume support 
; oe ws anys ae om 600K documents, DESQview for multitask- | * P9/2 micro channel adapters 
/ ¢ Compaq support 

Ve tested DOS 6 with and without MemMaker and with QEMM 6 and our new QEMM 7 ing, Novell Netware, IBMLAN Server | « Fine nes none 


uns away from all of them. See details of test conditions listed below. 
4 and DECnet for reducing the network | « 32-bit architecture for speed 


DOS 6 Giveth; DOS 6 Taketh Away driver memory footprint, plus games _* Esfaned compat in repos 
he best feature of new DOS 6 is the stable of utilities it includes. a une ee ee ne ie ics cele anaROM 
rouble is, they all eat up memory. DoubleSpace file compression needs a oe OR eine xd bus mastering hard 


oe and bus-mastering hard drive 
3K, Vsafe anti-virus needs 745K, Smartdrv disk cache needs 28K and others for fast action. You sacrifice all controlless 














ven Undelete takes 10-14K as a resident program. Using this when you turn va frame ae s DMA access into 
Aicrosoft's free memory utility, MemMaker, you could C/COm (which other Memory Supports Shadow RAM 
asily end up with a net loss of available ‘conventional’ Managers dlo fo maxi- 

mize available 


nemory in DOS 6. 


New QEMM 7 takes the best of the new DOS 6 
atures into account, finding ways to give you more 
ree memory for your program while taking full advan- 
age of DOS 6. One new QEMM 7 feature, DOS-Up 
noves the DOS 6 kernel, its data and resources to 
nemory above 640K (this feature also works with DOS 


memory above 640K). It’s this use of the page frame by 
Stealth that lets you set up your PC with a mouse, CD 
ROM, sound board, a network such as Novell 
NetWare, reserve 8-24K of extra memory for optimal 
MS Windows performance, use all of DOS 68 
memory-hungry utilities and still have more than 
630K available for your programs. (Compared to DOS 
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our programs. And QEMM 75 seemingly small feature : ! 

if supporting DOS 66 multiple configurations gives you the flexibility More Memory for Ever yone 

nd ease of setup that you expect (MemMaker doesn{t work well with Our seventh-generation thoroughbred QEMM has improved ease-of- 

- important DOS 6 santa oe why it makes more sea use, with Express Install and Help features. And for power users, 

"ver {o put your money on the best memory manager—QEMM. Advanced Install and editable parameters and troubleshooting hints. 
Page Frame: the Key to Your Future And QEMM 7 comes with Manifest, the award-winning memory 


analyzer—enhanced for more flexibility—from Pentium testing to lap- 


[here's been a lot of talk about our patent-pending Stealth technology. , | ntestns 
top battery reporting; network analysis to editable configuration files. 


ealous talk, mostly. Because nobody else can touch its performance. 


Jur Stealth ROM feature, pioneered in QEMM 6 frees 48-II5K of ROM The new and ever more exciting capabilities coming to your PC 
iddresses for use by TSRs and drivers. Our Stealth DoubleSpace will all compete for memory with your favorite applications, TSRs and 
eature, described above, frees another 40K. And as you might imagine, drivers. And that makes QEMM 7 the front runner in your efforts to get 
here's more to come. get the best performance out of your PC today—and tomorrow. 
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Quarterdeck International Ltd, B.L.M. House, Crofton Terrace, Dun Laoghaire Co. Dublin, Ireland Tel. (353) (1) 284-1444 Fax: (353) (1) 284-4380 
QEMM Users: upgrades are available from dealers. 
You can also buy direct from Quarterdeck. Call (800) 354-3222 ext. 1D7 and ask about our special Game Pack offer with your upgrade! 
How i the chart numbers CPU—486/33 ALR Power/business VEISA machine equipped with 16 megs of RAM and running MS-DOS 6, Comparisons were done using the following memory managers: QEMM 7, QEMM 6.02, MS-DOS 6 MemMaker. In addition to the driver (or drivers) 
required by each memory manager, the following drivers, DOS resources and programs were loaded for all comparisons: in the CONFIGSYS file: SETVER.EXE, DOS=HIGH, FILES=20, BUFFERS=10, STACKS=0.0, MVSOUND SYS, SNDBK12SYS, SLCD.SYS, DOS SHELL=statement, in the 


AUTOEXEC BAT file: VSAFE, MSCDEX, UNDELETE, LSL.COM, NE2000.COM, IPXODI.COM, NETX OR EMSNETX, MOUSE.COM, SMARTDRV.COM, PRTSCCAP.COM. 
©1993 Quarterdeck Office Systems. Trademarks are property of their respective owners. 
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Figure 1: (a) Sample error message; 
(b) nonportable statements; 

(c) portable statements (change to 
normal C-style typecasting). 





Figure 2: (a) Sample error message; 
(b) nonportable statement; (c) portable 
statement (change the return value to 
match the base-class return-value 


type). 


(continued from page 64) 

wise, Visual C++ allows extra semicolons 
in class definitions, as in Figure 4. HP 
C++ 3.05, on the other hand, does not 
correctly handle nested macro expan- 
sion; see Figure 5. Nor are the Visual 


C++ compiler #pragma warning(dis- 
able: 4xxx) directives— pragmas used 
in MFC to eliminate warning messages 
during compiles— available in UNIX. 

Templates and exceptions normally 
lead to nonportable code. Although 
VC++ doesn’t directly support templates 
or exceptions, Microsoft supplies a tem- 
plate generator and includes exception 
classes with MFC which are portable 
and can be used on all platforms. 


API Differences 
Of the various Windows API flavors 
(Winlo for Windows 3.1 for 16-bit ap- 
plications, Win32 for 32-bit NT apps, and 
Win32s for portable 32-bit applications), 
the Win32s API is the cross-platform 
Windows API. Win32s is available on 
Windows 3.1 with the Win32s DLLs and 
on Windows NT, Macintosh System 7 
from Microsoft, and UNIX from Bristol 
Technology. 

Additionally, MFC allows you to have 
a single set of source for Windows 3.1, 
Windows 3.1 with Win32s DLLs, Win- 
dows NT, UNIX, and Macintosh. The 
Win32s API builds on the Win16 API by 
adding features from Win32 and does 
not include nonportable functions from 
Win16. 

Consequently, you shouldn’t make 
calls to the Win16 functions in Table 1 


(a) file.C, line 109: error: jump 
initializer (did you forget a 


(b) default: . 
int Number = GetSomeNumber(); 





Figure 3: (a) Sample error message; 
(b) nonportable statements; 

(c) portable statements (enclose the 
statements in a pair of braces to 
explicitly define the scope of the new 





Figure 4: (a) Sample error message; 
(b) nonportable statement; (c) portable 
statement (the tailing semicolon after 
the macro must be deleted). 


since they’re not included in Win32s. 
The Win32 functions in Table 2, how- 
ever, have been included, as have the 
Win32 messages in Table 3. Finally, the 
Winl6 functions in Table 4 have been 
changed in Win32s. 








This lesson in survival hasn’t been 
lost on DataPak Software. We realize the 
time for “simply refining” existing tech- 
nologies has passed. We designed our 
new line of tools with a clean slate. What 
we created is revolutionary—PAIGE™. 

PAIGE is an advanced open archi- 
tecture document processor with unlim- 
ited uses. For the first time, programmers 
have complete control of all data ele- 
ments (text, graphics, containers, sound, 
video, etc.) and how they are incorpo- 
rated into your documents. 
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PAIGE is designed to solve today’s challenges. Whether 
struggling with changes in CPU architectures, operating systems, 
end-user expectations or cross platform integration, program- 
mers need new flexible tools to help them adapt. 

PAIGE was specifically developed to meet a wide range of 
developer’s needs. It uses no globals, breaks all segmentation 
barriers, and is not limited to a specific compiler, development 
system, class library or development methodology. 


Evolve or Perish. 
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DataPak Software believes that change creates opportunity. 
Let us show you how quickly and effectively today’s most 
sophisticated programming functions can be incorporated into 
your next generation of products. 

For complete PAIGE technical and pricing summaries 
please contact us at 1-800-327-6703. Free product demonstra- 
tion software can also be accessed through most major commu- 
nication bulletin boards and services. 


9317 NE Hwy 99 #G * Vancouver, WA 98665 ¢ Bus (206) 573-9155 * Fax (206) 573-9269 
Internet: datapak1 @aol.com * AOL: DATAPAK1 ¢ CIS: 76424,3027 « AppleLink: D0142 





Written in C, PAIGE is 
uniquely designed to provide: 








¢ “Platform” independence 
¢ Open architecture design 
¢ Unlimited text stylization 
¢ Non-rectangular shapes 
© Page layout capabilities 

¢ Embedded objects 

¢ Discontinuous selections 
¢ Virtual memory 


and it’s ROYALTY FREE 
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EPC C++ for UnixWare 
EPC C++ for Solaris 
EPC C++ for UNIX V.4 
EPC C++ for SPARC 
EPC C++ for DYNIX 
EPC C#++4+ for Intel 


EPC C++ is available on many UNIX 
platforms to allow you to port from machine to machine with a minimum 
of rewriting. A true native compiler with templates and graphic, 

EPC C++ offers optimized performance on 
numerous platforms including the ones listed above. Call us to find out 
more about EPC compilers for UNIX. — trademarks are property of their respective owners. 


C++°¢ FORTRAN 90 «© FORTRAN 77* PASCAL * MODULA-2 « ANSI C 


EDINBURGH PORTABLE COMPILERS 
20 VICTOR SQUARE ¢ SCOTTS VALLEY ¢ CA * 95066 ¢ 408 438 1851 * FAX 408 438 3510 * EMAIL info@epc.com 
17 ALVA STREET ¢ EDINBURGH ¢ EH2 4PH ¢ UNITED KINGDOM ¢ +44 31 225 6262 ° FAX +44 31 225 6644 
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Figure 5: (a) Sample error message; 
(b) nonportable statements; (c) port- 
able statements. 


(continued from page 68) 

Word Sizes, Structure Packing, and 
Byte-Ordering Issues 

Independent of the cross-platform tool- 
kit, you must pay attention to differences 
in byte ordering, word sizes, and struc- 
ture packing. 

In the Windows 3.1 environment, in- 
tegers are normally 16 bits wide; in most 
other environments, they are 32 bits 
wide. Example 1 is nonportable (but 
working) 16-bit Windows code. Porting 
this code to NT or UNIX would cause 
problems if the value of mOne was ever 
greater than 65,535 because it would 
suddenly become too large to fit into 
wTwo (which is only 16-bits wide); the 


Windows Sockets, 


RPC/XDR, 
Telnet, FTP... 






toolkits ... all in one 


+ + + 


fastfacts: 408.867.4742 
fax: 408.741.0795 
email: mktg@distinct.com 
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for Windows 


%* Windows Sockets, Berkeley Sockets 
Kernel, RPC/XDR, FTP and Telnet 


* 100% DLL (uses only 4K DOS memory) 
Uses less memory than any other DLL or 
TSR implementation even when loaded 


Up to 128 concurrent sockets 


Coexists with Novell, Banyan or LAN 
Manager at no additional cost 


Supports NDIS, ODI and Packet drivers; 
SLIP and PPP with scripting 


TCP Tools: FTP (drag and drop), TFTP, 
Telnet, LPR/LPD, Back-Up with TAR 


distinct 
408.741.0781 
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pee. 
pile glioc 
AlloeGDiMem 


- InterruptRegister 







| — 







interruptUnRegister 








Table 1: WIN16 functions not included in Win32s. 


wTIwo variable would wrap and start 
back at 0. Normally, C++’s strong type 
checking will not allow code like this 
to survive, so 16/32-bit problems are 
not common in C++ unless typecasting 
is used. 

























Another common 16/32-bit problem 
is structure packing. On 16-bit systems, 
compilers pack structures based on 16- 
bit boundaries by default. On 32-bit sys- 
tems, the compilers use 32- or 64-bit 
boundaries (they waste a byte here and 


Software 
I Dyakeabaterey mn etes 


We'll 

help 

YOu. Engineering 
mast er Camegie 


Master of 
Software 


Mellon 


University 


Carnegie Mellon University 
offers an academic program 
leading to a professional 
Master of Software 
Engineering (MSE) degree. 


For information contact— 


MSE Admissions Coordinator 
Software Engineering Institute : 
Carnegie Mellon University 
Pittsburgh, PA 15213-3890 


(412) 268-7713 
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Now you can get from 


A TO B 
without losing any ZZZZs. 











Sleepless nights. A thing of the past for GUI developers? 


Oey \ on = is ae os DY ee BVA eo - 


Visual Builder 2.1 saves you endless hours of tedious coding and fine- 
tuning of graphical user interfaces. You can visually layout, simulate 
and modify your GUI to build a solid prototype in just a fraction of 
the time. And producing a finished GUI application is just as fast 
when you add behavior to your layout using Visual Builder’s simple 
yet powerful scripts rather than hand-coding C callbacks. 


PLATFORM TO PLATFORM 





Visual Builder has always made it easy to build GUI based applica- 
tions on a UNIX® platform and move them to another UNIX 
platform or to a PC running Microsoft® Windows. Now you can also 
develop in Microsoft Windows and move your application to UNIX 
platforms just as easily. 


IDT tro UIMS 


Visual Builder is available as an Interface Development Tool and as a 
User Interface Management System, and you can upgrade from IDT 
to UIMS with only a phone call to activate the UIMS components. 





All trademarks are the property of their respective owners. 
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The IDT is a customizable GUI builder with WYSIWYG layout, 
simulator, automatic C code generator, and interface portability. 
The UIMS has the same robust features and adds powerful behavior 
scripting and the ability to integrate additional widgets for both 
Motif ™ and Microsoft Windows. 





GC i= om Aone, 


Try Visual Builder 2.1 FREE for 30 days. With our carefully designed 
tutorial you’ll be proficient in just a few hours. 
%* Call us toll-free at 1-800-565-5650 
+ Fax us at 1-416-496-8524 
% Send email to sepport @sni.ca 
%& Pull software and documentation off Internet using 
anonymous ftp at fip.e.net in the /vendor/Sietec directory. 


THE SIEMENS HERITAGE 


Sietec Open Systems is a division of Siemens in Canada. 

The Siemens name has always been synonymous with technological 
innovation - from laying the first trans-Atlantic communications 
cable to creating robots capable of seeing. 

With products like Visual Builder, this tradition continues. 


sieec 


OPEN SYSTEMS 














Table 2: Win32 functions included in Win32s (some functions are no-ops). 


(continued from page 7O) 

there to ensure that the elements of a 
structure are aligned properly). The end 
result is that the sizeof operator will re- 
turn different results in 16- and 32-bit 
environments. Structure packing can 
cause problems if you read structures 
to and from binary files. MFC does not 


write structures to file, but does not pre- 
vent the programmer from doing so. 
The other common portability prob- 
lem between Windows and UNIX is byte 
swapping. Some UNIX workstations, 
such as the Sun SPARCstation, have Big- 
endian (vs. Intel’s Little-endian) byte or- 
dering. This means that you can’t make 


assumptions about the order of bytes in 
structures. C++ does not protect the pro- 
grammer from these problems. Exam- 
ple 2(a) shows the byte-swapping prob- 
lem using classes from MFC. This code 
makes the fatal mistake of assuming that 
data in the DWORD dwPoint will be or- 


Several technical 
reasons exist for 
choosing the Windows 
API over Motif 





dered exactly the same as the tagPoint 
structure. To fix the problem, the type- 
casting is replaced by the Windows 
LOWORD and HIWORD macros to de- 
construct a DWORD properly. Example 
2(b) is a portable version of the CPoint:: 
CPoint(DWORD) constructor. 


Conclusion 

When it comes to cross-platform applica- 
tion development, the Windows API is 
more than a least-common denominator. 
This, coupled with C/C++ standards, 
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Custorn Nowe 





Requires only 6KB of base memor 
Implemented as 100% Windows DLL (not a TSR) 


@ All applications are both client and server 
= Works concurrently with NetWare, LAN Manager, Vines etc. 


= Up to 128 simultaneous sessions 
m@ Extensible SNMP Agent 


Developer Tools: 
Windows Socket API 
Berkeley 4.3 Socket API 
ONC RPC/XDR 
WinSNMP API 


Applications: 
TELNET (VT100, VT220), 
TN8270, FTP, TFTP 
SMTP/Mail, News Reader, 
POP, SNMP, Ping, Bind, 
Finger, Whois, Statistics, 
and Custom 
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NEW! Wee eae 


For overnight delivery call: 


(€] NETMANAGE” 
(408) 973-7171 


20823 Stevens Creek Blvd. 
Cupertino, CA 95014 USA 
Fax (408) 257-6405 





Check us out for the best 
Optical Character Recognition 
accuracy and the highest 
speed on the market. 


True 32 bit OCR engine 


Omnifont: 6 to 72 points 


Embedded spellchecker 


Outputs ASCII & RTF 


OCR Library and API Tool Kit 





Available for Windows, OS/2, 
Macintosh & UNIX. 


Fully featured end-user version 








Phone 
415.925.2323 415.461.4010 





available for evaluations. 


9 COGNITIVE 


TECHNOLOGY 


Larkspur, California 


Fax 


CIRCLE NO. 857 ON READER SERVICE CARD 


Dr. Dobb’s Journal, March 1994 


Intellicon-NT 960 


a RISC based multi-port 
I/O subsystem for 
serial communications 


Performance of 512 serial ports with 4 
* An on-board Intel 1960 host adapters in a system 


32 bit RISC processor 4 The ACM/ 16 module 
off-loads the serial I/O has both RJ45 and 
task from the main CPU DB25 connectors 


Offers up to 2MB of * Offers optional on-board 








on-board dynamic RAM realtime clock and optional 
for data storage on-board battery backup 
Offers up to 256KB of for the dual-ported RAM 
Table 3: Win32 messages included in on-board dual-ported  ¥% Supports 80286, 80386 
Win32s. RAM and 512KB Flash and 80486 AT bus 
EEPROM for data architecture 
storage and custom Software Flexibility 
application programs %* Development tools 
RISC-like quad UARTS available for custom 
with 24 bytes of FIFO development 
per channel provide high 4 Software support for 
speed data communi- UNIX, XENIX, QNX, 
cations up to IISK baud DOS 
on each port * bere 
Table 4: Win16 functions in Win32s. Hardware Flexibility ara ee Tech’s 


* The Intellicon-NT960 products have become 
subsystem includes a known for their unsurpassed 
NT960 host adapter, quality and reliability. This 
the ACM/ 16 external tradition of providing flexible 
communications — cost effective solutions is based 
module, software drivers on Connect Tech’s expertise in 


Call us today at telephone 519/836 /1291 or and manuals the design and manufacture 
facsimile 519/836 /4878 to find out more about Provides 16 to 128 asyn- — o¢ communication hard- 
the Intellicon-NT960 and other Connect Tech chronous serial ports ware and software. At 


communication products from one PC slot Connect Tech we meet 
* Accommodates a total your objectives — by design. 


onnect Tech Inc. 727 Speedvale Ave. W. Tel: 519-836-1291 


‘Meeting your objectives ..by design’ Guelph, ON N1K 156 Fax: 519-836-4878 





Example 1: Nonportable, 10-bit 
Windows code. 
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(dirp)) t= NULL ) 4 Wh Hil 
ana 


oath): 
antbuf, diventp->d_nane 


a ‘could use vi. 


itbuf .st_mode = direntp- off attrib; 
statbuf st size = direntp-off fsize 
dd.da_year = (direntp->ff_fdate >> 9) + 1980: 
See | 


dd.da_mon = (direntp-off fdate Prado 
wirector.c” Line 316 of ?57% ~~41 





Deals with |-D columns 


. Set a novice down in front of our ® Point-and-shoot file retrieval ° 
peo 2: (a) aa Intelligent Code Editor (ICE), even © Color support © Data lookup 
prooiem using MF C GSES) without a manual, and you'll expe- © Cut-and-paste between programs e Find procedure 
(b) a portable version of the rience something unusual. A lack * Bookmarks e Special COBOL search options 
CPoint::CPointtDWORD) constructor. of swearing. An intuitive approach. * Block renumber, shift and fill e Version switching 
A smooth and easy learning curve. ¢ Online help e Check length of literals 

make it an attractive environment for Productivity. Match brackets, quotes, etc. e Source reformatter (optional) 
programmers who have to support more ICE is fast, flexible, and easy to ° Record-and-playback macros A free ICE demo is available for 
than one platform. use. It runs on a variety of UNIX e Environment saved automatically DOS and many UNIX systems. 

With the great strides that software al Aven ac fst Als i alta Sé¢ GrrOKs flees sia platform and media 

{ wnen ordering. 

development tools are making, a year 2 Sucres Comparison g 


from now a cross-platform solution may Features include: 


be as easy as selecting a radio button © Pulldown menus Did somebody say COBOL? eS Rasmussen Software 
in your visual development environ- e Modeless editing ICE has unique features that 
ment’s Build Options dialog box. © One or two open windows support COBOL, including: "] lJ | / o 24-0 | a 
e Multiple open files e Automatic literal continuation 10260 SW Nimbus Avenue, Suite M2A 
DDJ e Logical use of PageUp, PageDn, etc. © Match IF/ELSE Portland, Oregon 97223 USA 
e Flexible function-key usage e Deals with page-line numbers Fax: 503/624-0760 


To vote for your favorite article, circle inquiry no. 7. 
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EXAMINING ROOM 





Ithough Microsoft calls the current 
incarnation of Visual Basic the “Vi- 
sual Basic 3.0 Professional Edition,” 
it wouldn't be stretching it to re- 
fer to it instead as “the Visual Basic Data- 
base Edition” because of the database 
Orientation of its tools and functionali- 
ty. In this article, I'll examine the Visu- 
al Basic 3.0 environment and related 
tools, presenting in the process a mul- 
timedia database application that uses 
a local Access database (MDB). I'll also 
discuss how you can revise this database 
so that you can use it with ODBC and 
a local dBase (DBF) file. Of course, 
you'll need an MDB, DBF, and ODBC 
data source with comparable table def- 
initions. 





Visual Programming 
You produce Visual Basic (VB) appli- 
cations by combining components in a 
systematic manner. The visual program- 
ming model promotes a division of labor 
between specialists who write custom 
controls and those who build applica- 
tions. In most cases, the process of 
building an application involves select- 
ing components and writing code that 
binds the pieces together. With VB, you 
create screens by defining forms con- 
taining Windows controls such as scroll 
bars, list boxes, text boxes, labels, and 
other user-interface objects. For each 
object, you set properties and generate 
code (methods) that executes in re- 
sponse to events. 

VB 3.0 includes an integrated database 
engine (the Access Engine), a database 
manager that works with multiple DBMS 


Ken has developed DBMS projects for 
mainframe, mini, PC, and client/serv- 
er systems and is currently writing a 
book about Windows multi-DBMS pro- 
gramming for Wiley & Sons. Contact him 
at Resource Group Inc., 2604B El 
Camino Real, #351, Carlsbad, CA 92008, 
or on CompuServe at 71301, 1300. 
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Ken North 


formats, support for OLE 2.0, messag- 
ing CMAPI), database connectivity 
(ODBC), multimedia (MCD, graphics 
(Graphics Server), and report genera- 
tion (Crystal Reports). VB does not sup- 
port pure object-oriented programming, 
DOS text mode, or an Xbase dialect. 
The large number of plug-in custom 
controls from third-party developers, 
however, covers a range of functionali- 
ty including telecommunications, fax, 
spreadsheets, calendars, imaging, graph- 
ics, data management, and GUI objects; 
see the text box entitled, “Add-on Data- 
base Tools for Visual Basic.” 


Custom Controls 

Custom controls are essentially plug- 
and-play components packaged in DLLs. 
Microsoft supports a specialized DLL— 
the VBX (Visual Basic eXtension)— with 
its VB and Visual C++ (VC++) compil- 
ers. The Professional Edition of these 
compilers includes 19 custom controls 
and a Control Development Kit (CDK). 
Developers who write custom controls 
using the CDK may produce three lev- 
els of controls based on compatibility 
with VB 1.0, 2.0, and 3.0. VC++ pro- 
grammers can use VBXs compatible 
with VB 1.0. 

Also noteworthy is that Microsoft 
Foundation Classes 2.0 Gncluded with 
VC++) contain classes that implement a 
VBxX-emulation layer for VB 1.0 controls. 
Controls used with C++ do not have the 
full functionality of VB 2.0/3.0 controls 
in several areas, including drag-and- 
drop behavior, run-time controls, con- 
tainer controls, and control arrays. 


The Database Connection 

One of the benefits of VB 3.0 is the sep- 
aration of the front end from the back 
end of a database application. In A 
Guide to Developing Client/Server SOL 
Applications (Morgan Kaufmann, 1992) 
Khoshafian et al. describe 12 rules for 
client software that include a client- 


Database Development 
and Visual Basic 3.0 


Putting a pretty face on client/server 
architectures 


autonomy rule whereby client software 
shall behave the same whether pro- 
cessing data at the client or server. VB 
3.0 provides that type of transparency: 
A user can run an application using vir- 
tually the same user interface whether 
the application operates in native mode 
on an MDB, attaches to local tables in 
other database formats, or connects to 
an ODBC server. VB provides a good 
vehicle for prototyping and debugging 
using the Access Engine for projects that 
run on an SQL server in their final form. 

JET, the Access 1.1 Engine, reads and 
writes databases in a variety of formats 
including Access, dBASE III and IV, Fox- 
Pro 2.x, Btrieve, Paradox 3.x, and a 
number of SQL (ODBC) databases. The 
Access Engine also provides query 
optimization, transaction processing, 
optimistic and pessimistic locking, dis- 
tributed multitable joins, and so on. 
However, although VB programmers can 
manipulate Access’s data, VB doesn’t 
support unique Access features such as 
forms and macros or the ability to run 
Access applications. Further, VB pro- 
grams cannot implement Access-style 
security from within VB. 

To develop a database application with 
VB, you can either use the Object Lay- 
er or data controls, both of which are 
supported by the Access Engine. The 
Object (or Programmatic) Layer is VB’s 
option for programmers who feel com- 
fortable writing code. Data-aware con- 
trols (or more commonly, data controls) 
are an easy-to-use noncode solution that 
constitutes VB’s Visual Layer. On the oth- 
er hand, some developers bypass the JET 
engine because they’ve chosen other 
means for building database applications. 
VB provides alternatives such as third- 
party database libraries and the ability 
to write directly to the API of database 
DLLs such as ODBC. 

Bound controls — data-aware controls 
that simplify access to a database— are 
a major new enhancement for database 
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Languages 
core fmm | | | CA-ClipperS'87 
cs a - CA-Clipper 5.01 or above : 
| CA-dBFast 
_| CA-Realizer 2.0 
1 Clarion 
FoxPro 2.0/2.5 for DOS 
FoxPro 2.5 for Windows 
Force 


- : | Paradox for Windows 
— | Pascal 
 . Visual Basic for Windows |_| 
Visual Basic for DOS 
| Generic Function Calls 


34575 59899 


Visually create reports and forms: Automatically generate source code: | 
¢ fully banded reports tied to data ¢ in most popular computer languages oe 
¢ graphics (.bmp, .pcx and .tiff) - portable between languages . 
¢ bar codes and labels ¢ fully customizable 

¢ invoices and other business forms| | ~+ easy-to-use functions 

° multi-fonted text ¢ royalty free 


Take advantage of Windows GDI compatibility towork 
with any printer, or make your reports really fly with direct 
PCL and PostScript support in Windows and DOS. | 








So have your cake and eat it. Get control with ease of use. , 
Here’s a tool that not only looks good, but also speakes your language. 
Try IN-PRESS risk free with a 30 day money back guarantee. 

For literature or to order IN-PRESS, call 1-800-533-3183. 





In PA: (215) 692-8130. 
FAX: (215) 692-8172 
BBS: (215) 631-5724 _ 
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developers. VB associates a bound con- 
trol with a specific database column or 
field. You create the association by bind- 
ing the control to the data control— a 
scroll bar associated with a dynaset 
query (a dynamic query result set), SQL 
statement, or QueryDef. Bound controls 
work with the Access Engine while the 
data control is associated with Dynaset, 
Snapshot, or tables. The Professional 
Edition has eight bound controls, and 
the Toolbox shows icons for Check box, 
Image, Label, Picture box, Text box, 
3-D check box, 3-D panel, and Masked 
edits. Combos and list boxes are not 
bound. 

Finally, it’s possible to bypass the en- 
gine using the SQL pass-through option, 
a tool for obtaining better performance 
and executing stored procedures at the 
server. However, you must manage your 
own connections if you use ExecSQL. VB 
and Access write to level 1 of the ODBC 
API so not all of the new features work 
with every ODBC driver. If you work 
with core-level ODBC drivers, you must 
continue to write directly to the ODBC 
Call Level Interface (CLD and forego the 
ODBC abstraction and new controls (of- 
ten preferable for performance reasons), 





isual Basic for Applications, for- 
merly called “Object Basic,” is the 
embedded language of Microsoft’s 
applications. Access Basic, WordBasic, 
and Visual Basic are older cousins of 


hancements in areas like macro record- 
ing, transportability, and object sup- 
port. VBA is the new programming 
tool for Excel 5.0 on the PC and the 
Macintosh, so the macro recorder now 
generates Visual Basic. 

The concept of programming with 


VB dialects. Access Basic and Visual 
Basic include objects such as Form, 
Dynaset, Report, and Database. Excel 
now has Cells, ActiveCells, Ranges, 
and collections like Sheets, Work- 
sheets, Charts, and Workbooks. Each 
edition of VB introduces more fea- 
ee . a 





z 
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the latest VB edition that includes en- 


objects is familiar to developers using © 





Figure 1: (a) Referencing objects in other applications from Visual Basic; 
(b) using an object from an EXE or DLL. 
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Access and VB provide an option to by- 
pass the Access Engine’s SQL parse of 
the SQL and pass it through to the ODBC 
data source. To use the pass-through op- 
tion and bypass the parse, set the data 
control’s Option property to SQL_ 
PASSTHROUGH. VB 3.0 supports trans- 
action processing with three statements 
(BeginTrans, CommitTrans, and Roll- 
back) that are preferred to the database 
methods from prior releases. 

VB’s data-access capabilities are not 
the only features useful for building 
database applications. Others include 
extensions for communications, object 
linking, report writing, graphics, and 
mail. VB includes Pinnacle’s graphics li- 
brary, Graphics Server SDK, and the 
Crystal Reports database report writer. 
Crystal Reports for Visual Basic includes 
a VBX that provides approximately 15 
of the 60 calls in the full API for the 
Crystal Reports print engine. The VBX 
is available at design time but hidden at 
run time. Crystal Reports for Visual Ba- 
sic doesn’t include the report compiler 
of Crystal’s Pro Edition, which provides 
the ability to compile reports into a 
stand-alone executable. Notably, Bor- 
land also bundles Crystal Reports with 
its database products. 


Visual Basic for Applications 


tures familiar to programmers using 


OOP languages such as Smalltalk, Ac- 


tor, and C++. The implementation of 


VB available with Excel includes an 
Object Browser, a familiar tool to OOP 
developers. Although the OOP-lan- 
guage browsers usually depict a class 
hierarchy within an application con- 
text, the Object Browser in VBA shows 
objects from other applications. An 
Excel user might browse and use ob- 
jects from Word for Windows, Fox- 


Pro, PowerPoint, Mail, Access, Project, 


Publisher, or other applications that 


- support OLE 2.0. VB programs refer- 


ence objects in other applications by 
statements such as that shown in Fig- 
ure 1(a). It is possible to use objects 
from EXEs or DLLs and to activate oth- 
er applications and send keystrokes; 
see Figure |(D). 


TD 


ous implementations of Lisp and REXX 






Another feature, OLE automation, 
permits objects to publish a set of com- 
mands and functions available to oth- 
er apps (CreateObject) and subscribe 
to those features in other applications 
(GetObject). OLE automation is a stan- 
dard feature in Microsoft applications; 
see the accompanying text box enti- 
tled, “Visual Basic for Applications.” 
You can use the OLE tool to add OLE 
2.0 automation to your applications, 
but VB doesn’t support the full set of 
OLE 2.0 features. 

The VB 3.0 CDK lets C++ program- 
mers create new VB controls. The prin- 
cipal change to the CDK for 3.0 was the 
addition of functions and messages for 
data-aware controls. 

VB isn’t the best platform for collab- 
orative projects because version-control 
tools that support code sharing for mullti- 
programmer projects do not compare 
with other languages. Microsoft has an- 
nounced an upcoming version-control 
system, but not a release date. Conse- 
quently, the most common current ap- 
proach is to save forms in ASCII. 


A Multimedia Database 
Video and database technologies are a 
natural marriage for some applications. 





Programmers familiar with the vari- 






may be surprised to learn the extent 
to which VB has become a full fea- 
tured programming language for mul- 
tiple computing platforms. In addition 
to VBA development, Microsoft is port- 
ing the VB Programming System to the 
Macintosh and Windows NT. NT 3.1 
and OLE 2.0 are the forerunners to 
Cairo, Microsoft’s object-oriented op- 
erating system. 
Microsoft is clearly positioning VB 
as a flexible tool for development with 
objects (OLE, Windows, and NT to- 
day; Mac and Cairo in the future). In 
the not-too-distant past there was a 
lot of interest in microprogrammable 
computers, those adaptable to specific 
application needs by using a writable 
control store and microcoded machine 
instructions. Lisp and Pascal machines 
were computers whose microcode 
gave the hardware a Lisp or Pascal 
personality. The industry today is mov- 
ing to RISC, not extensible architec- 
tures, but you wonder what the plan- 
ners at Redmond would do with an 
object-Basic machine. 
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One such example is an industrial data- 
base, where video is used as a tool to 
familiarize workers with physical lay- 
outs to minimize exposure to hazards 
or radiation. The program presented in 
this article is a typical database that in- 
cludes identifiers and evaluation data. 
The example is for a tennis academy, 
although you can easily modify it to fit 
different applications (a personnel data- 
base, for example). Once the applica- 
tion has been created, I’ll examine the 
revisions needed so you can use it with 
ODBC and a local dBase (DBF) file. The 
files you'll need for this project are avail- 
able electronically; see “Availability,” 
page 3. The example also uses the MCI 
custom control and Microsoft’s Video 





community includes many tool ven- 
dors competing to fill specific nich- 
es. One factor that gives some of these 
tools an edge is their usability with 
other languages. Developers working 
in multiple languages, or groups that 
include programmers with different 
language skills, can benefit from the 
ability to add libraries or custom con- 
trols that work with more than a sin- 
gle programming language. 
Microsoft bundles Crystal Reports 
from Ciystal Services | a0couyve. 
British Columbia) and Graph from Pin- 
nacle Publishing (Kent, Washington) 
with Visual Basic Professional Edition. 
However, both Visual C++ and Bor- 
land C++ 4.0 developers can add sim- 
ilar functionality. The Graphics Server 
SDK from Pinnacle Publishing pro- 
duces almost 20 graph types using in- 
stallable components for C/C++, SQL- 
Windows, Turbo Pascal, Powerbuilder, 
Actor, and Superbase. Graphics Serv- 
er’s architecture is similar to some Win- 
dows SQL engines. A single copy of 
the server sits in memory and services 
graphic requests in the form of DDE 
conversations or calls to one of the 
approximately 170 functions in its DLL 
(GSWDLL.DLL). Graphics Server man- 
ages the windows, and your applica- 
tion works with views in a manner 
similar to that of non-Windows graph- 
ics software. The coordinates in your 
program are relative to a view, not a 
window. GS SDK’s geometric functions 
include lines, circles, ellipses, filled ar- 
eas, and polygons. The text functions 
include titles, text, and numeric labels 
and legends. 
Q+E MultiLink/VB from Q+E Soft- 
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for Windows to play video clips. To use 
this feature, you must install the files 
from the \RUNTIME directory of the 
Drivers diskette of Video for Windows. 
Alternatively, you can download 
VFWRUN.ZIP from the WINEXT or 
MSAPPS forum libraries on CompuServe. 

The first step in creating the partici- 
pant form (PERSON.FRM) is to use a 
data control, which resembles VCR con- 
trols. This 3.0 control permits a user to 
step through query data using four but- 
tons: MoveFirst, MovePrevious, Move- 
Next, and MoveLast. To associate a form 
with a table in the database, select the 
Properties window, double-click on the 
DatabaseName property and select an 
Access filename from the DataBaseName 


ware (Raleigh, North Carolina) is a 
“middleware” tool that links VB ap- 
plications to PC and SQL databases — 
Oricic, Sybase. Ineres, SOL Server 
dBase, Clipper, Paradox, and Btrieve. 
The tool, which supports ODBC, 
includes 20 database drivers and 60 
new properties. Applications using 
these database drivers may be dis- 
tributed royalty free. MultiLink/VB also 
provides a number of development 
tools including a database manager, 
custom controls, and the Q+E Builder. 
New properties include edit masking, 
mapped list, combo boxes, and string 
searches in combo and list boxes. 

VBAssist from Sheridan Software 
(Mellville, New York) adds more than 
25 tools to the VB environnicit, 
including a Data Assistant to bind cus- 
tom controls to databases via drag- 
and-drop; a Form Wizard that gener- 
ates database forms which can contain 
uw bound bel, text fields, aod 
navigation buttons; and DB Assistant, 
a tool that allows the creation, testing, 
and wtidinienance Of an Access 
database from within VB. Data Wid- 
gets, also from Sheridan, is a set of 
bound controls for creating front ends 
to database applications. 

Integra VDB from Coromandel eat 
rest Hills, New York) includes an SQL 
engine and VBX controls for VC++ and 
VB. It includes Architecture controls 
and Visual controls. The Architecture 
controls are invisible abstractions of 
database objects. The Visual controls 
include a grid, text box, frame, radio 
button, combo box, list box, anda 
database-operations control. The Ar- 
chitecture VBXs include application, 
data-source, query, form-definition, 





dialog box. You must follow a similar 
procedure to select the query to run 
against the database by specifying a 
table name, an SQL statement, or a 
stored SQL query for the RecordSource 
property. 
The next step in the process is to add 
a number of bound controls linking the 
field on the form to a column in the 
table. Associate all data-aware controls 
with the data control and set all of the 
DataSource properties to the Datal con- 
trol. To do this, place the control on the 
form and complete its DataField prop- 
erty. VB will display a list of tables in 
the database. Following the design of 
the form, the next step is to add data- 
(continued on page 80) 
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and form-builder controls. Integra VDB 
also Das a call-level interface of ap- 
proximately 50 functions, including a 
frigser function which supports 
master- detail lookups that fire when 
the user activates bound visual controls. 

TrueGrid from Apex Software (Pitts- 
burgh, Pennsylvania) allows VB pro- 
grammers to create database browse 
tables that are editable and fully config- 
urable. To create a browse table, you 
drop TrueGrid onto a VB form and set 
the form’s DataSource property. True- 
Grid supports the same database for- 
mats as VB, but also allows you to 
create browse tables for custom data- 
bases. The tool also includes an ex- 
pression string syntax for calculating 
fields, and a design-time layout editor 
for interactive design. 

Finally, because the Access Engine 
does not support Clipper index files 
(NTXs), A.S. Inc. (Minot, North Dako- 
ta) has created vxBase 3.0 — a share- 
ware function library for VB or C/C++ 
programmers. vxBase includes a num- 
ber of functions, expressions, and op- 
erators whose syntax is similar to 
Xbase. A VB programmer can manage 
Clipper and dBase III/III+ data, memo, 
and index files with familiar functions 
such as vuxAppendBlank, vxPack, and 
uxZap. vxBase includes multiple DBF, 
NTX, xBase, Multiuser, Record Navi- 
gation, Memo, Logical, Date, Numer- 
ic, Field, Char, Record 1/0, File, 
Browse, Memory, and Windows In- 
terface functions. Programmers opting 
for the commercial product can order 
a developer’s kit that includes a roy- 
alty-free run-time DLL. 
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(continued from page 77) 

validation logic. Click on the data con- 
trol, select the Validate event and enter 
the code for your field validation. The 
person form (PERSON.FRM) of our ex- 
ample project validates the information 
in three bound text controls. The row 
or record must have a surname, a gen- 
der of M or F, and a category or rating 
between 10 and 70. 

To test the ODBC links, I used a pre- 
viously installed testbed of ODBC soft- 
ware and drivers. The next step was to 
install and test using more recent drivers 
from Q+E Software’s ODBC Pack and 
Microsoft’s Desktop Database Driver 
Pack. To use the participant form with 
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an ODBC database, you'll need to blank 
the DatabaseName property. Then, you 
need to complete the information in the 
Connect property. For example, if the 
name of the ODBC data source is PER- 
SONID, enter ODBC; DSN=PERSONID in 
the Connect property field and select the 
appropriate table name from the list asso- 
ciated with the RecordSource property. 

If you set the Connect property to 
ODBC and don’t enter a DSN string, VB 
will attempt an SOQLDriverConnect, 
which will prompt you with a list of 
ODBC data sources. If you want to cre- 
ate a result set (dynaset) from an SQL 
query, enter the SQL statement in the 
kecordSource property. For example, it 


NEW...STATE-OF-THE-ART DOCUMENT CONVERSION TOOL 
FOR DEVELOPERS AND END-USERS! 


DAVE IS CREATING 


DOCUMENTATION AND 


HELP FILES. 


NOW DAVE IS CONVERTING 


TO AND FROM 


WINDOWS HELP FILES, 
| EXPERT HELP/ NORTON GUIDES, 
MS WORD DOCUMENTS, 
WORDPERFECT DOCUMENTS, 
ASCII TEXT DOCUMENTS , 
dBase, FoxPro, CLIPPER AND 
PARADOX DATABASES! 


Like Dave, save an incredible amount oft time SS imize errors | 
with Multi-Doc™...the state-of-the-art document conversion tool. | 
With Multi-Doc, you create documentation and help files only once in 
DOS or Windows.. push a key and generate them in the format of your choice! 


Be a hero like Dave...contact us toll-free for a FREE DEMO or more 


information. 
1-800-533-3183 
in PA 215-692-8130 
FAX: 215-692-8172 © BBS: 215-631-5724 


For BOTH 
DOS & WINDOWS 


Conversion 


§ 7 99 


Royalty Free 





CIRCLE NO. 853 ON READER SERVICE CARD 


80 


might be common to view participants 
in rating order by entering SELECT * 
FROM IDENT ORDER BY CATEGORY 
for the RecordSource property. To use 
an attached dBase table, you need to 
set the Connect property to dBase III or 
dBase IV, specify the directory name for 
the DatabaseName property and spec- 
ify the table name as the RecordSource 


property. 
To develop a 
database application 
with VB, you can 
either use the Object 
Layer or data 
controls, both of 
which are supported 
by the Access 
Engine 





Conclusion 

Visual Basic is a versatile tool for client 
and client/server applications. The ap- 
plication presented here requires only 
minor changes to run with a variety of 
database formats; the data controls pro- 
vide quick and easy access to data even 
though they are not an optimal solution 
for high-performance applications. 

As an environment, VB often provides 
more than one solution, so you must 
evaluate the trade-offs between using 
VB at a high level of abstraction or get- 
ting down and dirty while writing to 
APIs. VB invites trade-offs because there 
are some projects where performance is 
critical, and others where ease-of- 
development is paramount. If you opt 
to write at the API level, you must learn 
hundreds of functions (including 50 for 
Crystal Reports and another 51 for 
ODBC) instead of pointing and clicking 
at the VBXs’ counterparts. When evalu- 
ating whether to jump in with VBXs or 
write directly to the APIs, consider the 
sheer volume of information: The ODBC 
1.0 reference manual, for example, is 
some 629 pages, the Graphics Server 
SDK almost 400 pages, Video for Win- 
dows about 250 pages, and the OLE 2.0 
manual nearly 700 pages. Throw in the 
Win and the Win32 APIs and you won’t 
want to see a bookstore anytime soon. 
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PROGRAMMER’S WORKBENCH 





Ithough 16-bit Windows doesn’t 
support preemptive multitasking 
of Windows apps, it does allow for 
preemptive, hardware-supported 
multitasking of “DOS boxes.” As you 
may know (especially if you have been 
following Andrew Schulman’s “Undoc- 
umented Corner” column in DDJ), this 
is accomplished by a protected-mode, 
virtual-machine operating system (the 
Virtual Machine Manager, or VMM) that 
kicks in when running Windows in En- 
hanced mode. Armed with this knowl- 
edge and faced with an aging DOS ap- 
plication crying for a modern user 
interface, what developer wouldn’t want 
the ability to graft a Windows front-end 
client onto a concurrently executing 
DOS back-end server? This is the 
premise behind WINGate from WINGate 
Technologies. 

WINGate allows a DOS program to 
communicate directly with a Windows 
application using a transaction-based 
API. Once this communication possi- 
bility is enabled, it leads to many inter- 
esting ways of exploiting the Windows 
environment. 





The Components 

WINGate Version 1.3x consists of a set 
of development components for build- 
ing your own client/server applications, 
a Windows Virtual Device Driver (VxD) 
for coordinating client and server pro- 
cesses, and a set of prebuilt client and 
server applets that you can use to per- 
form a few Windows operations — such 
as launching and killing Windows ap- 
plications — from the command level in 
a DOS box. Libraries are available for 
16-bit C and Visual C++, Pascal, Basic, 


Walter is a Boston-based freelance 
developer and consultant specializing 
in system tools and interfaces between 
applications and NT, Windows, and 
DOS. He can be reached on CompuServe 
at 73730, 553. 
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Porting from DOS 
to Windows 


WINGate’s client/server framework 
minimizes recoding 


Walter Oney 


Visual Basic, Clipper, Foxpro, dBase, 32- 
bit C (Watcom, Zortech, and MetaWare), 
and more. WINGate requires Enhanced- 
mode Windows, which of course im- 
plies an 80386 CPU. 

WINGate’s target market is developers 
who want to preserve the value of an 
existing DOS application by attaching a 
Windows GUI. Accordingly, I tried it out 
by using a simple client/server database. 
I found this aspect of WINGate to be 
eminently usable and well thought-out. 
I did, however, encounter a performance 
problem that might require attention in 
a commercial-grade product (more on 
this later). The WINGate package, in ad- 
dition to its libraries, includes ancillary 
components such as prebuilt applets 
and an installation program. 

WINGate comes on a single 3.5-inch 
diskette with a Windows-based instal- 
lation program, which copies the files 
and adds a DEVICE= line to your SYS- 
TEM.INI. While generally smooth, the 
install program does suffer from minor 
glitches. For example, unless you pre- 
vent it, it replaces your DOS PATH set- 
ting with a single entry for the WIN- 
GATE directory. Another problem has 
to do with version stamping. The Win- 
dows 3.1 API provides a standard facil- 
ity for stamping executable files with 
version information via the resource 
script. An install program should com- 
pare the version of a diskette-based file 
with any pre-existing copy on your hard 
drive, to avoid overwriting a more re- 
cent version. WINGate includes files that 
will presumably be redistributed by 
many developers. Since these files lack 
the resource version information, it’s 
possible that the wrong version could 
end up on an unsuspecting end user’s 
machine. 


The Simplest Client/Server Application 

To investigate WINGate, I built a simple 
client/server database application. The 
“database server” (Listing One, page 100) 


is a real-mode DOS application that pro- 
vides, on request, the name of the capi- 
tal city of any country in the known uni- 
verse — provided the country is within a 
small table located within the program. 
The client (Listing Two, page 100), a sim- 
ple database-query generator, is a Win- 
dows app that asks the user for a coun- 
try and then displays that country’s capital. 

This simple project was a breeze. I 
used C8 (the command-line compiler 
that forms the backbone of Visual C++ 
1.0) on a 486/33 and had a working ex- 
ample in about two hours. The printed 
manual contains excellent and accurate 
documentation of the 32 functions in 
the API; the API routines themselves are 
aptly named. A short overview of client 
and server programming at the begin- 
ning of the manual gives a step-by-step 
cookbook for building the programs, 
and sample code illustrates all the steps. 
The sample code shows a DOS-based 
client and a Windows-based server, 
however. Since I was building a DOS- 
based server and a Windows-based 
client, an example of this converse sit- 
uation would have helped. 

Many programmers may have trouble 
using WINGate successfully, I fear. This 
has much less to do with WINGate itself 
than with the difficulty of client/server 
applications in general and communi- 
cation-based protocols in particular. I 
find WINGate easier to use than most 
network protocols because it imposes 
much less of a burden on me to estab- 
lish the initial connection. 

The code for a Windows-based client 
is found in CLIENT.C. As you can see, 
the client registers itself as a WINGate 
user during processing of a WM_CREATE 
message via a call to WGRegister(), pass- 
ing an argument (in this case, client), 
which is a unique, system-wide name 
identifying this particular WINGate client. 
My example’s identifier isn’t particular- 
ly unique; you might want to use 
wsprintf to generate a unique string 
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(continued from page 8&2) 
based on your task or instance handle. 

My example does not do much error 
checking; you certainly would need to 
add this in a production application. 
For example, a production application 
should ensure that the corresponding 
server is up and running. You could use 
WinkExec() to launch the server and 
then use various WINGate services to 
establish a connection. Alternatively, 
you could use the WGServerInfo API to 
get a list of available servers and veri- 
fy that the one you wanted is up and 
running. For this demonstration, I man- 
ually started the server in a DOS box. 

Selecting a country within the list box 
which occupies the client area triggers 
a database query using the code in Ex- 
ample 1. The first three API calls setup 
a transaction packet to ask the database 
server what the capital of the selected 
country is. WGExecute transmits the 
packet to the server, and WGGetResponse 
waits until a response occurs. WGGet- 
TransString extracts the answer to the 
query as a null-terminated string, and 
WGDestroyTrans cleans up by releasing 
the resources associated with the trans- 
action. 

The server-side code that responds 
to queries is equally simple. You use a 
DOS-only API function named WGinit 
to initialize the WINGate package and 
another function called WGRegisterServer 
to register the program as a WINGate 
server. You now enter a loop in which 
you poll for transactions; see Example 
2. The additional API calls in the server 
are WGPostkesponse, which sends a re- 
sponse back to the client, and WGGet- 
TransID, which gets the query transac- 
tion’s ID for use in posting the response. 
I detect a shutdown or cat mae 


WGTRANS trans = We 
WGSetTransString ( 
WGSetTransValue ( 
long tid = WGExec 
WG_STAT_ WAIT_RES 
WGGetResponse(tr 


webeatroytranattces 


PROGRAMMER’S WORKBENCH 


within the transaction- processing code 
by checking for a zero-return from 
WGGetTrans Value(trans, 1, &code). 

A WINGate transaction includes eight 
32-bit data fields whose use is entirely 
up to the client and server programs. 
WGSetTrans Value is used to set these 


Difficulties are not 
with WINGate, but 


with building 
client/server 
applications in 
general and 
communication- 
based protocols in 
particular 


fields, and WGGetTransValue, to get 
their values. I used field number 1 as 
an opcode, with 0 meaning “shutdown” 
and 1 meaning “query the database.” 
Looking at Listing One, you'll notice that 
the WM_DESTROY message sends a 
transaction, to which no response is ex- 
pected, containing a 0 opcode. This is 
the only normal way the server can be 
made to exit. The use of 0 here is de- 
liberate, by the way, since WGGetTrans- 
Value also returns 0 if there’s an error. 

Within the DOS-based server pro- 
gram, I’ve shown you the call to WGGet- 


. 80); Se 


ver", 1000, 


WATT. _RESPONSE) : 
sizeof (capital)) 





Example 1: A Windows client creating a transaction using WINGate. 


WGTRANS trans 
af (trans) 
{ 


7 ee eet 


ji process transaction 
WGGetTransString(trans, country, sizeof(country)); 





// [code that looks up capital ciey deuce _ 


- WGTRANS response = 


WGSetTransString (response, 


long tid = 


WGDestroyTrans (response) ; 





WGCreateTrans("server", strlen(capital)+1) ; 
capital): 

WGGetTransID(trans, 
WGPostResponse(response, tid); 


&code) ; 


Example 2: The corresponding DOS server responding to the transaction. 
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Trans that polls for a query transaction. 
But suppose no transaction is available 
at a particular time. The WINGate man- 
ual doesn’t say what to do. Normally, 
the right thing to do is to give up your 
time slice by issuing interrupt 2F/1680, 
and that’s what my sample program 
does. The Windows scheduler then 
allows other virtual machines to run. 
Unfortunately, the scheduler then also 
imposes a 50-millisecond execution 
penalty before the yielding virtual ma- 
chine is again eligible to run. In the case 
of my sample, I saw a noticeable delay 
between selecting a country and seeing 
the response, and I infer this is due to 
the scheduling penalty. 

The WINGate VxD could overcome 
the scheduling penalty by using the 
Wake_Up_VM and Set_Execution_Focus 
services judiciously. Alternately, WIN- 
Gate could include a “wait-for-transac- 
tion” API that would cause the VM to 
block on a semaphore. The driver does 
appear to use the Suspend_VM and No_ 
Fail_Resume_VM services to suspend 
and resume a DOS virtual machine in 
some cases (perhaps when a DOS pro- 
cess does a WGGetkesponse), but these 
services perform more slowly than VxD 
semaphore services. 


Prebuilt Clients and Servers 
WINGate includes several matched pairs 
of client and server applets. For exam- 
ple, there is a DOS-mode client program, 
WINSPAWN, that communicates with a 
WinApp server named WGSPAWN in or- 
der to launch new DOS or Windows 
programs. You’re supposed to use these 
applets by starting the Windows-side 
server program (perhaps using the 
LOAD= directive in WIN.IND ahead of 
time. You then use the DOS-side client 
program as necessary to direct the server 
to perform some function or another. 

I found the rationale for these applets 
a bit mysterious and also encountered a 
problem when using one of them. After 
first launching all the necessary Windows- 
side server programs, I started a DOS ses- 
sion and used the WINSPAWN client to 
launch a copy of NOTEPAD; see Exam- 


(a) C:\WINGATE>winspawn notepad 
Execution OK ==> 11591 


‘() C:\WINGATE>winctrl -ms 
#11591 300 240 300 24@ 
Execution OK ==> @ . 


© G: Ne ane #11591 


Execution 0 => 0 





Example 3: (a) Using WINSPAWN to 
launch Windows NotePad from DOS; 
(b) using WINCNTRL to resize the 
NotePad window; (c) using WINKILL 
to shut down NotePad. 
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ple 3(a). An instance of NotePad then ap- 
peared on my desktop. Presumably, the 
number (11591) displayed on the confir- 
mation line is NotePad’s task handle, in 
decimal. I then used WINCTRL to resize 
and move the NotePad window; see Ex- 
ample 3(b). Predictably, the NotePad win- 
dow moved. Finally, I used WINKILL to 


WINGate is for 
developers who 
want to preserve the 
value of an existing 
DOS application by 
attaching a 


Windows GUI 





close out this copy of NotePad; see Ex- 
ample 3(c). NotePad then asked me if I 
wanted to lose my unsaved changes (I'd 
done some typing in the NotePad window) 
and exited. Throughout it all, the DOS 
“client” commands executed asynchron- 
ously from the Windows side. In other 
words, WINSPAWN returned before 
NotePad was actually up and running, 
WINCTRL returned before NotePad’s win- 
dow was moved, and so on. This sequence 
left my Windows session in a sorry state — 
I couldn't pull down any menus! Acceler- 
ator keys worked correctly, however, so I 
tried to exit from Windows. At this point 
a system modal dialog told me that Win- 
dows was extremely low on memory, 
whereupon I rebooted my computer. 

Even assuming my experience was 
atypical, I still wonder whether these lit- 
tle utilities are useful. Since you obvi- 
ously won't type these commands in a 
DOS box if you can just move the 
mouse, they will likely be used from a 
.BAT file. It isn’t easy, however, to cap- 
ture stdout output like “Execution OK 
— 11591” to save the task handle you'll 
need for later commands. You can, of 
course, simply use the name of an ap- 
plication in WINCTRL or WINKILL, but 
you then face the possibility of moving 
(or closing!) the wrong window if mul- 
tiple instances are active. Moreover, no 
synchronization primitives are available 
at the command level that let you wait 
until an app is launched before you try 
to kill it, for example. 


The Clipboard Applets 


At first glance, it seems that the WIN- 
CLIP/WGCLIP pair of applets provide a 
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useful function. Normally in Windows, 
if you want to paste a bitmap or spread- 
sheet file from one app to another, you 
first open an application that under- 
stands the file, mark the portion you 
want to copy, copy it to the clipboard, 
paste it into the target application, and 
then close the originating app. With 
WINCLIP, you can put the whole file di- 
rectly onto the clipboard with a single 
DOS command: winclip dib to @\win- 
dows\cars.bmp. ; 

Leaving aside the messy command 
syntax, I find the implementation of 
WINCLIP disappointing. The Windows 
shell already exports an INT 2F/17xx in- 
terface by which a DOS box can inter- 
act with the clipboard. (See Tom Olsen’s 
article, “Making Windows and DOS Pro- 
grams Talk,” Windows/DOS Developer's 
Journal, May 1992.) Apparently, WIN- 
CLIP doesn’t use this interface. If it did, 
it wouldn’t need to have a matching 
server or use the WINGate VxD. There 
would, moreover, possibly be more clip- 
board formats available. 


Conclusion 

Despite my quibbles about the ancillary 
pieces of WINGate, I think it is a very 
worthwhile tool. The WINGate concept 
of coupling DOS and Windows appli- 
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cations with a client/server API mediated _ 
by a VxD has considerable technical 
charm. The author of WINGate has 
done a good job of creating an API and 
a set of libraries to facilitate the task. 
Many commercial-product develop- 
ers will prefer to move whole-hog to a 
Windows implementation without con- 
sidering the potential simplification that 
products like WINGate offer. On the 
other hand, I’ve fielded enough ques- 
tions at industry forums to know that 
corporate developers and individual con- 
sultants will appreciate a less thorough- 
going and more pragmatic alternative. 
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BINARY DATA 


Listing One (Text begins on page 18.) 


typedef struct { 
enum ddr_op operation; 
struct ddr_ops *operations_vector; 
void * ddr_public; /* for application usage */ 
char * ddr_private; /* for internal use 1 */ 
char * ddr_base; /* for internal use 2 */ 
int nCount ; /* for internal use 3 */ 
J DDR; 


struct ddr_ops { 
BOOL (*getlong) (); 
BOOL (*putlong) (); 
BOOL (*getshort) (); 
BOOL (*putshort) (); 
BOOL (*getbytes) (); 
BOOL (*putbytes) (); 
void (*destroy) (); 


ddr_op { 
DDR_ENCODE 
DDR_DECODE 


Listing Two 


#ifdef unix /* used in Ddr.h (via makeheaders) */ 


#if defined(sparc) |; defined(rs6@00) |; defined (hp7@@) || defined (m88k) 
#define BIG_ENDIAN 

#define ALIGNED 

#elif defined(i86) || defined (vax) 

#define LITTLE_ENDIAN 

#elif defined (mips) 

#define LITTLE_ENDIAN 

#define ALIGNED 

#tendif 


/* Move<type>(from,to) */ 
/* 
* Byte moving, with byte-swapping. 
* For use on 68000, sparc and most of the riscs 
*/ 
#if defined (BIG_ENDIAN) 


#define MoveByte(pSrc, pDest) 


(*(char*) (pDest) = *((char*) (pSrc)) ,1) 
#define MoveShort (pSrc, pDest) = 


(*(char*) (pDest) = *((char*) (pSrc)+1),\ 
*((char*) (pDest)+1) = *(char*) (pSrc) ,2) 


#define MoveLong(pSrc, pDest) (*(char*) (pDest) = *((char*) (pSrc)+3),\ 


HALO IMAGING TOOLS 
GIVE PROGRAMMERS THE 


POVVER TO VVRITE 
IMAGING MAGIC. 


Sophisticated tools for today’s programmers 

who need state-ofthe-art imaging in their 

C and C++ applications. Create powerful image- 
enabled programs with the first multi-platform 
imaging API from Media Cybernetics. 

Slash months from your development effort 
with our award winning, market-proven 


technology. 


HALO Imaging Library™ 


#elif defined (LITTLE_ENDIAN) 
#ifndef ALIGNED 


*((char*) (pSre)+2) ,\ 
*((char*) (pSre)+1),\ 


* ((char*) (pDest) +1) 
* ((char*) (pDest) +2) 


/* Low-level byte moving, without byte-swapping. Use these definitions for 386 
* and other low-enders ciscs that dont have alignment constraints. (vax) */ 


#define MoveByte(pSrc, pDest) 
#define MoveShort (pSrc, pDest) 
#define MoveLong(pSrc,pDest) 
#else 


/* use this for mips(ultrix) 


#define MoveByte(pSrc, pDest) 
#define MoveShort (pSrc, pDest) 


#define MoveLong(pSrc, pDest) 


#endif 
#else 


(*(char *)(pDest) = *(char*) (pSrc) ,1) 
(*(short *)(pDest) = *(short*) (pSrc) ,2) 
(*(long *)(pDest) = *(long*) (pSrc) ,4) 


and may be other riscs (alpha) */ 


(*(char *)(pDest) = *(char *) (pSrc),1) 
(*(char*) (pDest) = *((char*) (pSre)),\ 
*((char*) (pDest)+1) = *(char*) (pSrce)+1,2) 
(*(char*) (pDest) = *((char*) (pSre)),\ 
*((char*) (pDest)+1) = *((char*) (pSrce)+1) ,\ 
*((char*) (pDest)+2) = *((char*) (pSre)+2) ,\ 
*((char*) (pDest)+3) = *(char*) (pSrc)+3, 4) 


#ferror "unknown machine architecture" 


#endif 
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Listing One (Text begins on page 26.) 


/* C Parameters passed on call stack */ 
double SquareIt ( double dValue ) { 
return ( dValue * dValue ) ; 


} 


/* Clipper Parameters aquired through API functions */ 
CLIPPER SquareIt ( void ) { 
double dValue = @.@ ; 
// if one parameter of type numeric 
if ( _parinfo (@) ==1 
&& _parinfo ( 1 ) == NUMERIC 


{ 

// grab parameter from Clipper 
dValue = _parnd (1) ; 

} 


// send return value to Clipper 

_retnd ( dValue * dValue ) ; 

return ; 

} 
/* FoxPro Parameters passed in a data structure */ 
void SquareIt ( ParamBlk *pParmBlk ) { 

double dValue = @.@ ; 

// if one parameter of type numeric 

at (*pParamBlk) .pCount == 

&& (*pParamBlk) .p[@].val.ev_type == 'N' ) 


{ 
// grab parameter 
dValue = (double) (*pParamBlk) .p[@].val.ev-real ; 


// send return value to FoxPro 
_RetFloat ( dValue * dValue , 12 , 4) ; 
return ; 


} 
Listing Two 


/* Setup for wrapping functions */ 
#ifdef _FAMILY_C // parameters passed on call stack 
#define SquareIt(PARMLIST) SquareIt ( double dValue ) 
#ednif 
#ifdef _API_FOX // FoxPro requires a global data structure 
FoxInfo myFoxInfo[] = 
{ { "SQUAREIT" , (FPFI) SquareIt , 1 , "N" } } ; 
FoxTable _FoxTable = 
{  (FoxTable*) @ 
, Sizeof(myFoxInfo) / sizeof (FoxInfo) 
, myFoxInfo 


#endif 
/* Prototypes */ 
TYPE_D SquareIt ( PARMLIST ) ; 
double _SquareIt ( double ) ‘ 
/* Wrapping function (without error handling) */ 
TYPE_D SquareIt ( PARMLIST ) { // ( dValue ) 
// declare return value (and any other local values) 
DECL_D ( dReturn ) ; 
// prepare to accept parameter(s) 
PREP_D (1 , dValue ) ; 
// grab parameter(s) from host API 
GRAB_D (1 , dValue ) ; 
// call core function 
dReturn = _SquareIt ( dValue ) ; 
// send return value to host API 
SEND_D ( dReturn ) ; 
} 
/* Core function */ 
double _SquareIt ( double dValue ) { 
return ( dValue * dValue ) ; 
} 


Listing Three 


/* C translation of wrapping function */ 
double SquareIt ( double dValue ) 
{ 


// DECL_D ( dReturn ) ; 
double dReturn = 9.0 ; 
// PREP_D (1, dValue ) ;: 


// GRAB_D ( 1 , dValue ) ; 


// call to core function 

dReturn = _SquareIt ( dValue ) ; 

// SEND_D ( dReturn ) ; 

return dReturn ; 

} 
/* Clipper translation of wrapping function */ 
void SquareIt ( void ) 


{ 

// DECL_D ( dReturn ) ; 

double dReturn = 9.@ ; 

// PREP_D (1, dValue ) ; 

double dValue = G.@ ; 

// GRAB_D (1, dValue ) ; 

dValue = dAPIgrab ( 1 ) ; 

// call to core function 

dReturn = _SquareIt ( dValue ) ; 

// SEND_D ( dReturn ) ; 

_retnd ( dValue ) ; 

return ; 

} 
/* FoxPro translation of wrapping function */ 
void FAR SquareIt ( ParamBlk* gpFoxParm ) 

{ 


// DECL_D ( dReturn ) ; 
double dReturn = @.@ ; 
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// PREP_D (1, dValue ) ; 

double dValue = 9.0 ; ; 

// GRAB_D (1, dValue ) ; 

dValue = dAPIgrab ( 1 , gpFoxParm ) ; 
// call to core function 

dReturn = _SquareIt ( dValue ) ; 

// SEND_D ( dReturn ) ; 

_RetFloat ( dReturn , 12, 4) ; 
return ; 


} 
Listing Four 


/* Setup for wrapping functions */ 
#ifdef _FAMILY_C // parameters passed on call stack 
#define FlipIt(PARMLIST) FlipIt ( APISTR wspText ) 
#ednif 
#ifdef _API_FOX // FoxPro requires a global data structure 
FoxInfo myFoxInfo[] = 
{ { "PLIPIT" . (FREI) FlipiIt . 1... °C" 33 ; 
FoxTable _FoxTable = 
{  (FoxTable*) @ 
, Sizeof(myFoxInfo) / sizeof (FoxInfo) 
» myFoxInfo 


#endif 
/* Prototypes */ 
TYPES FlipIt ( PARMLIST ) ; 
WSTR* _FlipIt ( WSTRt)  ; 
/* Wrapping function (without error handling) */ 
TYPE_S FlipIt ( PARMLIST ) { // ( wspText ) 
// declare return value (and any other local values) 
DECL_S ( wspReturn ) ; 
// prepare to accept parameter (s) 
PREP_S (1 , wspText ) ; 
// grab parameter(s) from host API 
GRAB_S (1 , wspText ) ; 
// call core function 
wspReturn = _FlipIt ( wspText ) ; 
// send return value to host API 
SEND_S ( wspReturn ) ; 
; 
/* Core function */ 
WSTR* _FlipIt ( WSTR* wspText ) 
{ 
// storage for return value 
static char szaReturn [ 256 ] ; 
// WSTR wrapper for return value 
static WSTR wsReturn ; 
// pointers for string flip loop 
char *cpOld , *cpNew ; 
// counter for string flip loop 
ushort u ; 
// point return WSTR at return buffer 
wsReturn.cp = szaReturn ; 
// set return length to incoming length 
wsReturn.uiLen = *wspText.uiLen ; 
// limit return length to size of return buffer 
if ( wsReturn.uiLen > ( sizeof ( szaReturn ) - 1 ) ) 
wsReturn.uiLen = ( sizeof ( szaReturn ) - 1 ) ) ; 
// set up loop variables 
u = wsReturn.uiLen ; 
cpNew = szaReturn ; 
cpOld = *wspText.cp + u - 1 ; 
// flip old into new 
while ( u-- ) 
*cpNewt+ = *cpOld-- ; 
// zero terminate regardless of host API 
*cpNew = '\O' ; 
// return WSTR pointer 
return ( &wsReturn ) ; 


} 
Listing Five 


/* C translation of wrapping function */ 
char* FlipIt ( char* wspText ) 


{ 
// DECL_S ( wspReturn ) ; 
WSTR wsReturn ; WSTR *wspReturn = éwsReturn ; 
// PREP_S ( 1 , wspText ) ; 
WSTR wsBuffi ; 
// GRAB_S (1 , wspText ) ; 
if ( wspText == NULL ) 
{ 


wsBuff1.cp = (char*) "\xFF" ; // defined as NIL 
wsBuffi.uiLen = (ushort) 1 ; 
} 
else 
{ 
wsBuff1.cp = (char*) wspText ; 
wsBuffi.uiLen = (ushort) strlen ( wsBuffi.cp ) ; 
} 


wsBuff1.ulHnd = QL ; 

wspText = &wsBuff1 ; 

// call to core function 

wspReturn = _FlipIt ( wspText ) ; 

// SEND_S ( wspReturn ) ; 

return *wspReturn.cp ; 

} 
/* Clipper translation of wrapping function */ 
void FlipIt ( void ) 

{ 

// DECL_S ( wspReturn ) ; 

WSTR* wspReturn = (WSTR*) (void*) OL ; 

// PREP_S ( 1 , wspText ) ; 

WSTR wsBuffi ; WSTR* wspText = éwsBuff1 ; 


(continued on page 90) 
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Listing Five (Listing continued, text begins on page 20.) short iReturn ; 
// PREP_I (1 , iStyle ) ; 


// GRAB_S (1, wspText ) ; : 

_bcopy ( wspText , wspAPIgrab (1) , sizeof ( WSTR ) ) ; // SET_ERR_NONE ( ) ; 

// call to core function ( _iIpErrCode (@) ) ; 

wspReturn = _FlipIt ( wspText ) ; // GRAB_I (1 , iStyle ) ; 

// SEND_S ( wspReturn ) ; ; 

_retc ( *wspReturn.cp ) ; // if ( IS_ERR_NONE ) ... 

return ; if ( ( _ilIpErrCode ( -32767 ) ==@) ) 

} iReturn = ( * ( (short*) _vpIpSet ( 8@ + 512 , &iStyle ) ) ) ; 
/* FoxPro translation of wrapping function */ // SET_ERR_LOC ( "IpBoStyle" ) ; 
void FAR FlipIt ( ParamBlk *gpFoxParm ) ( _wspIpErrLoc ( szaaswsp ( "IpBoStyle" ) ) ) ; 

{ // TRAP_ERR ( ) ; 

// DECL_S ( wspReturn ) ; if ( ! ( _ilpErrCode ( -32767 ) ==@) ) 

WSTR* wspReturn = (WSTR*) (void*) OL ; vErrTrapC ( ) ; 

// PREP_S (1, wspText ) ; // SEND_I ( iReturn ) ; 

WSTR wsBuffi ; WSTR* wspText = &wsBuffl1 ; return iReturn ; 

// GRAB_S ( 1, wspText ) ; } 

_MemCpy ( wspText 


, wspAPIgrab ( 1 , gpFoxParm ) End Listings 


, sizeof ( WSTR ) 


// call to core function 

wspReturn = _FlipIt ( wspText ) ; 

// SEND_S ( wspReturn ) ; 

_RetChar ( wspReturn && *wspReturn.cp 


? *wspReturn.cp 
. on 


ie 
while ( (*gpFoxParm).pCount ) 
if ( (*gpFoxParm) .p[--(*gpFoxParm) .pCount] .val.ev_type == 'C' ) 
_HUnLock ( (*gpFoxParm) .p[(*gpFoxParm) .pCount].val.ev_handle ) ; 
return ; 


Listing Six 


/* An In-Press wrapping function (with error handling) */ 
TYPE_I IpBoStyle ( PARMLIST ) { // ( [iStyle] ) 

DECL_I ( iReturn ) ; 

PREP_I (1 , iStyle ) ; 

SET_ERR_NONE ( ) ; 

GRAB_I (1 , iStyle ) ; 

if ( IS_ERR_NONE ) 

iReturn = GETSET_I ( HND_BO_STYLE , iStyle ) ; 

SET_ERR_LOC ( "IpBoStyle" ) ; 

TRAP_ERR ( ) ; 

SEND_I ( iReturn ) ; 

} 


/* The C translation of an In-Press wrapping function */ 


short IpBoStyle ( iStyle ) { 
// DECL_I ( iReturn ) ; 
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-INT FILES 


Listing One (Text begins on page 36.) } 
while( stremp(buff,t_section) ); 
/* Now that the section has been found, find the entry. 


[ ERA REREK KEKE AERA KAKA RAKE EKA EEK KA EEK AK KAKA AE EAE EEA EEA EAE EEE ERERE * Stop searching upon leaving the section's area. */ 
PORTABLE ROUTINES FOR WRITING PRIVATE PROFILE STRINGS -- by Joseph J. Graf do 
Header file containing prototypes and compile-time configuration. { if( !read_line(fp,buff) |; buff[@] == '\@' ) 
HAKKAR EEE EE KAKA AKAK AKER AKA AAA KA KEKE KE KEKE ERE KEK ERE RE EK EEE EE EEEEEEEREREEES / {  fclose(fp); 
strncpy (buffer ,def,buffer_len) ; 
#define MAX_LINE_LENGTH 80 return(strlen (buffer) ); 
} 
int get_private_profile_int(char *, char *, int, char *); } while( strncmp(buff,entry,len) ); 
int get_private_profile_string(char *, char *, char *, char *, int, char *); ep = strrchr(buff,'='); /* Parse out the equal sign */ 
int write_private_profile_string(char *, char *, char *, char *); eptt; 
/* Copy up to buffer_len chars to buffer */ 
Listing Two strncpy(buffer,ep,buffer_len - 1); 
buffer[buffer_len] = '\@'; 
/***** Routines to read profile strings -- by Joseph J. Graf ***##*/ fclose(fp) ; /* Clean up and return the amount copied */ 
#include <stdio.h> return(strlen(buffer)) ; 
#include <string.h> } 
#include "profport.h" /* function prototypes in here */ 
e e 
[ RHEE AEA A KAKA EA EAE EA KEK KAKA AK EEE AA KAKA KARA EAE EERE Listing Three 
* Function: read_line() 
* Arguments: <FILE *> fp - a pointer to the file to be read from /***** Routine for writing private profile strings --- by Joseph J. Graf *****/ 
* <char *> bp - a pointer to the copy buffer #include <stdio.h> 
* Returns: TRUE if successful FALSE otherwise #include <string.h> 
EEEEARK EKA EK KAKA EKA KK AKE EA EEA KEEEEEEAE AEE EK EE EREEEREEEEEEEREREEE RE / #include "profport.h" 
int read_line(FILE *fp, char *bp) 
{ char c= '\@'; [ RAKAAKAAKEKAKEAE AEA EE EE EEKE KEKE KEKE EK EK EK EAA AAA AE RA ERE RAKES ER ERE EE EERE 
int i=9; * Function: write_private_profile_string() 
/* Read one line from the source file */ * Arguments: <char *> section - the name of the section to search for 
while( (c = getc(fp)) != '\n' ) * <char *> entry - the name of the entry to find the value of 
{ if( c == EOF ) /* return FALSE on unexpected EOF */ * <char *> buffer - pointer to the buffer that holds the string 
return (Q) ; * <char *> file_name - the name of the .ini file to read from 
bp[itt+] = ec; * Returns: TRUE if successful, otherwise FALSE 
KAKAKAAAAA KAS AEA AKAEKAK AEE KAKAKEA RAKE EA EEAREREE EEE ES EAE EER ER EERE REE EEE / 
bp[i] = '\O'; int write_private_profile_string(char *section, 
return(1); char *entry, char *buffer, char *file_name) 
d 
[ 8RRAKAKEAE AKA KE EEAEEKEK EEE EEE EK EEE EKER EEA EA EK AAA AAA A EAE EK ERE RE REE EE { FILE *rfp, *wfp; 
* Function: get_private_profile_int() char tmp_name [15]; 
* Arguments: <char *> section - the name of the section to search for char buff [MAX_LINE_LENGTH¥] ; 
ad <char *> entry - the name of the entry to find the value of char t_section[MAX_LINE_LENGTH] ; 
* <int> def - the default value in the event of a failed read int len = strlen(entry); 
* <char *> file_name - the name of the .ini file to read from tmpnam(tmp_name); /* Get a temporary file name to copy to */ 
* Returns: the value located at entry sprintf (t_section,"[%s]",section) ;/* Format the section name */ 
HAKAAKAAKAKAL KAKA KARA KEKE KEE KAKA KAKA EAA EEA EERE AA AERA ERE RE AEE RARE EEE / if( !(rfp = fopen(file_name,"r")) ) /* If the .ini file doesn't exist */ 
int get_private_profile_int(char *section, { if( !(wfp = fopen(file_name,"w")) ) /* then make one */ 
char *entry, int def, char *file_name) { return(@); } 
{ FILE *fp = fopen(file_name,"r") ; fprintf (wfp,"%s\n",t_section) ; 
char buff [MAX_LINE_LENGTH¥] ; fprintf(wfp,"%s=%s\n",entry,buffer) ; 
char *ep; . 
char t_section[MAX_LINE_LENGTH] ; (continued on page 92) 


char value[6]; 

int len = strlen(entry) ; 

int i; 

if( !fp ) return(@); 

sprintf (t_section,"[%s]",section); /* Format the section name */ 


i: Move through file 1 line at a time until a section is matched or EOF */ Build your Own Neural Net! 
and Expert System! 


{ if ( !read_line(fp,buff) ) 
{ fclose(fp); 
return (def) ; 


‘idiot mecca liebe ecesieiony 1: EASY NEURAL NETWORKS 
Easiest way to quickly learn about 


/* Now that the section has been found, find the entry. 
* Stop searching upon leaving the section's area. */ 


do es se e 
{ if( !read_line(fp,buff) |; buff[@] == '\@' ) this fascinating new technology 
- includes a working Neural Network 
} e 
} while( strncmp(buff,entry,len) ); you can train! $59 *K KK 
ep = strrchr(buff,'='); /* Parse out the equal sign */ p 
eptt; A 
if( !strlen(ep) ) /* No setting? */ 
tetrlen(ep) EASY EXPERT SYSTEMS 
/* Copy only numbers fail on characters */ Build your own Expert System in about 
shee Ti ett ce ad one day! Includes 40-Page Knowledge 
value= NO" Engineering Manual, Quick Ref Card 
fclose(fp); /* Clean up and return the value */ ngineering anual, Quic € ar 
_ eee for quick start, and powerful Stock 
[44444ATEEREEEEEEEEEEESEE EE EREEESEEEE SEES EAAA EES EADAI EES EEES TEETER EEE EE TEE Market Expert System! $69 KKK * 
* Function: get_private_profile_string() 
* Arguments: <char *> section - the name of the section to search for 
* <char *> entry - the name of the entry to find the value of 
* <char *> def - default string in the event of a failed read BOTH $99 sd Includes 3 BIG Catalogs 
* <char *> buffer - a pointer to the buffer to copy into and FREE Talking Expert System Demo 
* <int> buffer_len - the max number of characters to copy 
* <char *> file_name - the name of the .ini file to read from 7 
* Returns: the number of characters copied into the supplied buffer + Order now and Fecelve @ free copy 
KAKKKKKEKK KKK KKK KKK KKK KEKE EERE EERE AAA AERA AEE EK KKKEKEKKKEKAKKARKKER EEE | of talking PC Therapist 7 usually $64 95 
int get_private_profile_string(char *section, char *entry, char *def, ° 


; char *buffer, a nee eas *file_name) 3 Catalogs & Demo Disk - Send your check for $5 
FILE *fp = fopen(file_name,"r") ; 
char buff [MAX_LINE_LENGTH] ; We always pay postage 
char *ep; e 6 e e ! 
oro | enlace ae: Please specify disk size or we ship 3.5 
int len = strlen(entry) ; - Check, American Express, or P.O. to: 


if( !fp ) return(@); 
sprintf (t_section,"[%s]",section) ; /* Format the section name */ 


: "(is)", _/* Format the sect THINKING SOFTWARE, INC. 
* Move through file 1 line at a time until a section is matched or EOF */ 
. if( !read_line(fp,buff) ) 46-16 65TH PLACE 
fclose | WOODSIDE, N.Y. 11377 PHONE (718) 803-3638 


{ fclose(fp); 
strncpy (buffer,def,buffer_len) ; 
return(strlen(buffer) ); 
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-INT FILES 


Listing Three (Listing continued, text begins on page 36.) fprintf(wfp,"%s\n", buff) ; 
} while( read_line(rfp,buff) ); 


fclose(wfp) ; } 

return(1); else 
} { fprintf(wfp,"%s=%s\n",entry, buffer) ; 
if( !(wfp = fopen(tmp_name,"w")) ) while( read_line(rfp,buff) ) 
{ fclose(rfp); { 

return (9) ; fprintf(wfp,"%s\n", buff) ; 


} 
/* Move through the file one line at a time until a section is 
* matched or until EOF. Copy to temp file as it is read. */ /* Clean up and rename */ 
fclose(wfp) ; 
do fclose(rfp) ; 
{ if( !read_line(rfp,buff) ) unlink (file_name) ; 
{ /* Failed to find section, so add one to the end */ rename (tmp_name, file_name) ; 
fprintf(wfp,"\n%s\n",t_section) ; return(1); 
fprintf (wfp,"%s=%s\n", entry, buffer) ; 
/* Clean up and rename */ 
fclose(rfp) ; og? 
fclose(wfp) ; End Listings 
unlink (file_name) ; 
rename (tmp_name, file_name) ; 
return(1); 


} 
fprintf (wfp,"%s\n", buff) ; 
} while( strcemp(buff,t_section) ); 


/* Now that the section has been found, find the entry. Stop searching 
* upon leaving the section's area. Copy the file as it is read 
* and create an entry if one is not found. */ 

while( 1 ) 

{ if( !read_line(rfp,buff) ) 

{ /* EOF without an entry so make one */ 
fprintf (wfp,"%s=%s\n",entry, buffer) ; 
/* Clean up and rename */ 
fclose(rfp) ; 
fclose(wfp) ; 
unlink (file_name) ; 
rename (tmp_name, file_name) ; 
return(1); 


} 


if( !strnemp(buff,entry,len) |; buff[@] == '\O' ) 
break; 
fprintf (wfp,"%s\n", buff) ; 


if( buff[@] == '\®' ) 

{ fprintf(wfp,"%s=%s\n", entry, buffer) ; 
do 
{ 
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CIRCLE NO. 910 ON READER SERVICE CARD 


Listing One (Text begins on page 40.) 


/* Machine dependent information required by front-end 


#ifndef CALLCONV_H 


#include "callconv.h" 


#endif 


#ifndef LANGUAGE_H 


#include "language.h" 


#endif 


#ifndef FP_H 
#include "fp.h" 
#endif 

#ifndef TCLASSES_H 


#include "tclasses.h" 


#endif 


typedef unsigned long inline_flags_type; 


typedef enum { 
CPU_unknown, 


CPU_I386, 
CPU_3790, 
CPU_RT, 
CPU_AM29K, 
CPU_I86@, 
CPU_MC68000, 
CPU_MC68020, 
CPU_VAX, 
CPU_MDD, 
CPU_SPARC, 
CPU_R3000, 
CPU_HOBBIT, 
CPU_PARISC, 
CPU_Ix86, 
CPU_RS600@, 
CPU_PPC 

} CPU_type; 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


/* 
/* 
/* 
/* 


Intel 386 */ 
IBM 370 */ 
IBM RT */ 
AM29000 */ 
Intel 860 */ 
Motorola 68000 +*/ 


Motorola 68020 */ 
DEC VAX 
McDonald Douglas */ 
SPARC (Sun 4) */ 


MIPS R3000 */ 

HP99@0-600/700/80@ PA-RISC */ 
80x86 -- 16-bit Intel */ 
IBM RS-6000 */ 
IBM Power PC */ 


/*Object module formats*/ 


typedef enum { 
NOFORMAT, 
COFF, 
AMDCOFF , 
LAMDCOFF , 
INTELOMF , 
ADOTOUT, 
ELF, 
MACH, 
HPUXCOFF, 


/* OMF not applicable or unknown*/ 
/* Basic AT&T COFF 
/* AMD version of COFF 


/*AMD version of COFF (little-endian mode) */ 


/* 
/* 
/* 
/* 
/* 


} objformat_type; 


/* Operating systems */ 


typedef enum { 
NOOS, 
AIX_OS, 
BSD_OS, 
SUN_OS, 
ATT_OS, 
EPI_OS, 
VMS_OS, 
MSDOS_OS, 
0S2_0S, 
XNX_OS, 
ISIS_OS, 
ATT4_OS, 
NeXT_OS, 
NEWS_OS, 
MSNT_OS, 
SOL_OS, 
HPUX_OS, 
} os_type; 


Intel OMF (MSDOS) 

BSD a.out 

SVR4 ELF format 

MACH object module format 

HPUX version of COFF 
/* OS unknown */ 
/* IBM's UNIX */ 
/* Berkeley UNIX BSD4.x */ 
/* Sun OS */ 
/* AT&T UNIX System V.3 */ 
/* EPI-OS (AM29@00) */ 
/* DEC */ 
/* MS-DOS */ 
/* OS/2 */ 
/* Xenix */ 
/* Isis */ 
/* AT&T UNIX System V.4 */ 


/* 
/* 
/* 
/* 
/* 


NeXTStep from NeXT */ 


Sony NEWS-OS */ 
Microsoft NT */ 
Solaris */ 
HP UNIX System V. */ 


/* Inline transcendentals */ 
Px POOGOOO1 
Px POOOGOGO2 
Px DODDOOO4 
Dx PBOOWOOO8 
QxO0GOOG19 
Dx POOOOO2B 
DxDOPDOO4D 
Px POODOG8B 
#define ATAN2_INLINE @x000G010G 
#define SINH_INLINE @x®0000200 
#define COSH_INLINE @x®0G@00400 
#define TANH_INLINE @x®000G80@ 
#define FABS_INLINE @x@00@1000 
#define ASM_INLINE @x®@0002000 
#define INS_INLINE %x®@00G4000 


#define SIN_INLINE 
#define COS_INLINE 
#define ASIN_INLINE 
#define SQRT_INLINE 
#define LOG_INLINE 
#define EXP_INLINE 
#define TAN_INLINE 
#define ATAN_INLINE 


/* Status of pragma processing: */ 


typedef enum { 


OKAY_DELETE_p, /* 


OKAY_PASS_ 


Pp, 


TOO_LATE_p, 


ERROR_p, 


IGNORED_p, 


} PRAG_STATUS; 
struct struct_aligns {char if_its_this_big, align_to_this;}; 


/* 
/* 
/* 
/* 
/* 


Pragma fully processed; do not pass to backend 
Pass pragma to back-end */ 
Pragma specified too late */ 


/* 
/* 


/* Arctan(a,b) */ 


/* tanh */ 
/* fabs */ 
= 
/* 


*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 


*/ 


Arcsin or Arccos */ 


Natural or common log */ 


ASM directive supported */ 
_inline(bytes) */ 


Suboperands of pragma incorrect */ 


badptr set to bad parameter */ 


Already specified */ 


extern struct mapping_entry{ 
/* False if structs are packed by default */ 
bool align_members; 
ubyte shortsize; 


ubyte intsize; 
ubyte longsize; 


ubyte floatsize; 
ubyte doublesize; 


size 
size 
size 
size 
size 


"short" in bytes 
"int" ~ in bytes 
"long" in bytes 
"float" 
"double" 
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*/ 
*/ 
*/ 
*/ 
*/ 


DESIGN 


*/ 


ubyte longdoublesize;/* size of "long double" */ 
ubyte min_parm_align;/* Min alignment of a passed parm */ 
bool unsigned_char; /*"char" unsigned by default? */ 
bool pure_32_bit; /* All integer operations in 32 bits?*/ 
ubyte code_ptr_size; /* Code pointer size */ 
ubyte data_ptr_size; /* Data pointer size */ 


/* Size of "near" pointer to code */ 
ubyte near_code_ptr_size; 
/* Size of "far" pointer to code */ 
ubyte far_code_ptr_size; 
/* Size of "near" pointer to data */ 
ubyte near_data_ptr_size; 
/*Size of "far" pointer to data */ 
ubyte far_data_ptr_size; 


ubyte short_align; /* Alignment of shorts */ 
ubyte long_align; /* Long alignment */ 
ubyte int_align; /* int alignment */ 
ubyte ptr_align; /* pointer alignment */ 
ubyte double_align; /* double alignment */ 
ubyte max_field_align; /* Maximum field alignment */ 
bool msb_first; /*integers stored MSB first? */ 
/* Align all vars to int boundary (even chars) */ 


bool word_align_vars; 

bool off_boundary_refs;/* Are off-boundary refs supported?*/ 

char *version; /* Version number of compiler */ 

/* Align structs 3 bytes or longer to word boundary */ 

bool word_align_structs; 

calling convention_set default_calling_convention; 

/* If true varargs must be explicitly specified with "..." syntax */ 

bool ansi_varargs_only; 

/* Which transcendentals may be inline? */ 

inline_flags_type inline_flags; 

ubyte max_parm_align;/* Max alignment of a passed parm */ 

ubyte offset_size; /* Pascal offset size */ 

ubyte area_size; /* Pascal area size */ 

/* Largest array in bytes (Pascal) */ 

unsigned long max_data_size; 

bool signed_halfwords_preferred; /*True for 370. (Pascal) */ 

bool range_checks_require_range; /*Do we need a lower and upper 

value for rangecheck?*/ 

/* How are Pascal sets mapped? */ 

/* Also see "set_unit_size" below */ 

bool sets_mapped_LSB_first; 

/* used in machines where pointer arithmetic will not work unless the 
* computed address is a multiple of machine's word size. */ 

ubyte address_resolution; 

/* In creating a common block for Professional Pascal interface packages, 
* we use the name of the package, prefixed and suffixed with a 
* special character. */ 

/* char to be prefixed to Pascal package block*/ 

char package_prefix; 

/* char to be suffixed to Pascal package block*/ 

char package_suffix; 

/* size of "char" in bytes, believe it or not char is 8 bytes on NAM */ 

ubyte charsize; 

/* Format of floating point */ 

real_form floating_point_format; 

/* If off-boundary references are NOT supported, do we 
* handle packed structures nevertheless? */ 

bool packed_structs_supported; 

ubyte char_align; /*Alignment of "char" */ 

ubyte float_align; /*Alignment of "float" */ 

ubyte longdouble_align; /*Alignment of "long double" */ 

char bits_per_int; /*bits per integer used for bitfields */ 

/* Implies the machine can convert (signed|unsigned) (char;short) to float 
* in a way more efficient than to double. The result is that the front 
* end is careful to generate FLT vs FLTU in this context so back end can 
* tell from register length and FLT/FLTU whether to generate the better 
* code and which kind of better code (it differs from U to nonU). */ 

bool short_to_float; 

/* Given the case index of a pseudo-function that target machine is 
* usually supports, do we support it with corrent configuration? */ 

bool (*recognize_pseudo_function) (func_case_index) ; 

CPU_type cpu; /* Target CPU */ 

os_type os; /* Target OS */ 

objformat_type omf; /*Target OMF*/ 

/* For non-padded structs, search this array, terminated by {0,0}. 

* If struct size is >= first member, align to at least 2nd member. 
* Thus "word_align_structs" could be (3,4},{2,2},{0,0}. ¥*/ 
struct struct_aligns *struct_aligns, *array_aligns; 
bool use_INFO; /* Can code generator tolerate INFO 
* rather than LINE/FILE/STAB ? */ 

type_class wchartype; /* this can be any intger type */ 

ubyte wcharsize; /* sizeof (wchar_t) */ 

/* We changed the way debugger information is passed to code generator. 
* If "debug_info_scheme" is 0, then old way is used. Otherwise, the 
* new way. */ 

ubyte debug_info_scheme; 

bool try_supported; 

bool wchar_is_short; /* wchar_t is short int */ 

bool wchar_is_long; /* wchar_t is long int */ 

/* Given a toggle that may have been defined in 
* establish_machine_dependencies, is it still good at this point? */ 

/* Return TRUE if so. Otherwise, the compiler will issued */ 

/* "Toggle cannot be specified here." */ 

bool (*toggle_is_valid) (toggle t, bool turn_it_on); 


/* "init", if not zero, is called when the first non-pragma is seen. 
* Its primary purpose is to adjust other fields in mapping that are 
* dependant on pragmas and toggles. E.g. 1167 toggle for 386 causes long 
* doubles to be 8 bytes instead of 12 */ 

void (*init) (void) ; 

/* The default global aliasing convention. NULL implies "%r". */ 

char *global_aliasing_convention; 

/* Are "far" variables support? That is, does it make 
* sense to qualify a variable declaration with "_far"? */ 

/* This must be FALSE on ESA/37@. */ 

bool far_variables_supported; 

/* Are "far" functions supported? If false, compiler will */ 


(continued on page 94) 
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DESIGN 


Listing One (Listing continued, text begins on page 40.) 


/* ignore "_far" and issue a warning. */ 
bool far_functions_supported; 
Does the target machine's OMF handle multiple named */ 
control sections (segments)? */ 
If this is false, then the front-end will ignore */ 

"pragma code", "pragma literals(xx)", and "pragma static_segment()". */ 
(Pragma data is handled on UNIX by converting to named blocks). */ 

bool multiple_named_sections_supported; 

/* Can control sections of class "common" be initialized? */ 

/* On DOS and VMS this is true. */ 
bool common_section_initialization_supported; 

/* Are we generated code for a strict IEEE machine? */ 
If true, we must generate unordered comparisons. */ 


/* 
/* 
/* 
/* 
/* 


/* 
/* 


I.e., 


X < Y is a different operation than !(X >= Y). */ 


bool IEEE_unordered_compares_supported; 
/* code_sections_supported -- if true, the target machine */ 


/* had separate I & D spaces but is able to reference the */ 
/* I space as data. (E.g.,386 with its segment override). */ 
/* If set to TRUE, the toggles "const_in_code" and "literals_in_code" 

* will be supported for putting const variables into instruction space.*/ 
bool code_sections_supported; 
/* Is the calling convention "CALLEE_POPS_STACK" supported? */ 
bool callee_pops_stack_supported; 
/* Is the calling convention "REVERSE_PARMS" supported? */ 

/* (Applies to those machines that have a "PUSH" instruction only. */ 
bool reverse_parms_supported; 
/* Default data aliasing convention for Professional Pascal */ 
/* Default routine aliasing convention for Professional Pascal */ 
char *data_aliasing_ convention; 
char *routine_aliasing convention; 


/* 


set_unit_size 


in conjunction with the "sets_mapped_LSB_first" */ 


/* flag above determine how (Pascal) sets are mapped in storage. */ 
/* High C/Professional Pascal ordinarily maps sets as a sequence 
* of halfwords. Microsoft maps them as an even number of bytes, 


* 


ubyte set_unit_size; 


MSB first. */ 


/* type_checking is true if type information should be kept even when 
* g flag is off. This is used for 370/ESA type checking at link time. */ 
bool type_checking; 
/* Size of a "long long" type. If such types are not supported, 
* then the size should match "long". */ 
ubyte longlongsize; 


ubyte longlong_align; 


/* Alignment 


of long long */ 


/* What is the largest auto-variable of type struct that can be mapped 

* directly into a series of one or more registers? Value is in bytes. */ 
uint largest_aggregate_in_registers; 
/* When doubles or long doubles are just plain variables (or arrays 

* thereof), what should the alignment be? For Pentium, it's much 

* better for them to be 8-byte aligned. */ 


ubyte double_variable_align; 


/*double variable alignment */ 


/*Alignment of "long double" variable */ 
ubyte longdouble_variable_align; 
/* Code generator supports call-lit construct. */ 
/* These tell if we require certain calling convention bits: */ 
/* Must have cc_CALLEE_POPS_STACK. */ 
bool callee_pops_stack_required; 
bool reverse_parms_required;/* Must have cc_REVERSE_PARMS.*/ 
/* For C++ constructors/destructors of static/global variables, does 
* get handle the initialization level protocol? True for systems 
* that support .init/.fini sections. */ 
bool support_initialization_order; 
/* Use Sun's and AT&T's convention for mapping bit fields? */ 


bool supports_call_lit; 


bool ABI_bit_fields; 


/* SYS_SIZETTYPE takes on one of the values s, i, 1 for short, int, long. 
* SYS_SIZETSIGNED takes one of the values s, u, or n for signed, 
* unsigned or non-signed (for "char"). */ 
char sizet_signed; 
‘char sizet_type; 


}mapping; 


extern const char *machine_name; 
#define LONGLONG_SUPPORTED 


#define 


/* CHARSIZE is always the same on all 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


/*Pointer that is loaded into 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
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SYS_PACKEDSTRUCT 


SYS_CHARSIZE 
SYS_INTSIZE 
SYS_FLOATSIZE 
SYS_DOUBLESIZE 
SYS_EXTENDEDSIZE 
SYS_LINKSIZE 
SYS_LONGLONGSIZE 
SYS_SHORTSIZE 
SYS_LONGSIZE 
SYS_SIGNEDCHAR 


SYS_PTRSIZE 
SYS_DPTRSIZE 
SYS_CPTRSIZE 
SYS_WCHARSIZE 
SYS_WCHARTYPE 
SYS_WCHARSHORT 
SYS_WCHARLONG 
SYS_SIZETSIGNED 
SYS_SIZETTYPE 
BITS_PER_BYTE 
BITS_PER_INT 
BITS_PER_LONG 
SYS_INTAL 
SYS_LONGAL 
SYS_LONGLONGAL 
SYS_SHORTAL 
SYS_FLOATAL 
SYS_CHARAL 
SYS_DOUBLEAL 
SYS_LONGDOUBLEAL 


SYS_DOUBLE_VARIABLE_AL 


/* s, u, n. */ 
f*# a. 4, 1. 


c not supported currently. */ 


/*Name of machine*/ 
(SYS_LONGLONGSIZE > SYS_LONGSIZE) 


(!mapping.align_members) 


machines. Wrong!! not on NAM */ 


mapping. charsize 
Mapping.intsize 
mapping. floatsize 
mapping. doublesize 
mapping. longdoublesize 


mapping .near_ 


data_ptr_size 


mapping. longlongsize 
mapping. shortsize 
mapping. longsize 
(!mapping.unsigned_char) 


reg*/ 


SYS_LINKSIZE 


mapping. 
mapping. 
Mapping. 
mapping. 
mapping. 
mapping. 
mapping. 
mapping. 


mapping. 


data_ptr_size 
code_ptr_size 
wceharsize 
wchartype 
wcehar_is_short 
wchar_is_long 
sizet_signed 
sizet_type 


bits_per_int 


(sizeof (long) *BITS_PER_BYTE) 


mapping. 
mapping. 
mapping 
mapping. 
mapping. 
mapping. 
mapping 
mapping. 
mapping. 


SYS_LONGDOUBLE_VARIABLE_AL \ 


int_align 
long_align 


. longlong_align 


short_align 
float_align 
char_align 


.double_align 


longdouble_align 
double_variable_align 


mapping. longdouble_variable_align 
#define SYS_PTRAL 


#define SYS_OFF_BOUNDARY_REFS 


#define SYS_STRINGAL 


#define SYS_MSB_ 
#define SYS_LSB_ 


FIRST 
FIRST 


#define SYS_STACK_AL 
#define SYS_32_BIT_ARITHMETIC_ONLY mapping. pure_32_bit 


#define SYS_MAX_ 


#define SYS_WORD_ALIGN_STRUCTS 


FIELD_AL 


#define SYS_ADR_RESOLUTION 
#define SEGMENT_REG_SIZE 


SYS_INTSIZE ) 


#define NEW_DEBUG_INFO 


/* Establish_machine_dependencies -- 


mapping. ptr_align 
mapping.off_boundary_refs 

1 /*Alignment of strings*/ 
mapping.msb_first 
(!SYS_MSB_FIRST) 
mapping.min_parm_align 


mapping.max_field_align 
mapping.word_align_ structs 


mapping. address_resolution 
(mapping.far_data_ptr_size - \ 


(mapping.debug_info_scheme> 9) 


initializes "mapping" to correspond 


* to "machine". Returns FALSE if machine is not recognized. */ 
extern bool establish_machine_dependencies ( 
const char *machine, language_type 1); 
/* Defines which object module formatter should be used for the target OS and 
* machine name of the target operating system passed by the driver */ 
extern const char *targetos_name; 


Listing Two 


#define LS (sizeof (long) *8) 
#define BS (sizeof(long long) *8) 


/* Maximum bits for left shift */ 
/* Maximum bits for long long shift */ 


struct longlong{ /* Define structure for systems that don't support long long*/ 


long lo; 
long hi; 
}: 


typedef struct longlong Big_int; 
/* Grab a mantissa from a floating point number */ 
static long extract_mantissa(FP_number F) { 


Big_int b; 
int cnt, rbi 


t; 


cnt = BS -1 - F->Exp; /* Determine how far to shift to find exponent */ 
if (cnt >= LS){ /* If shifting at least a longword */ 
/* subtract longword length from shift count */ 


ent -= LS; 
if ( 


ent == @) 


rbit = long(b.lo) < @; /* Guard bit needed? */ 


b.lo 
b.hi = @; 
} 
if (cnt) 
rbit = 


= b.hi; 


{ /* Anything left to shift? */ 


(b.lo & (1L << (ent-1))) !=@; 


if (cnt == LS){ /* Some machines can't shift by long word length */ 


/* Defend against this. Result would be zero */ 


-lo = ((unsigned long)b.lo >> ent | (b-hi << (LS-cnt)); 


b.lo = @; 
b.hi = @; 
} 
else{ 

b = 
b.hi = 
} 

} 

} 


Listing Three 


#ifndef Process_h 
#define Process_h 


#include "addrvect.h" 
#include "disassem.h" 
#include "itemnumb.h" 
#include "linklist.h" 
#include "memacces.h" 
#include "modulemg.h" 
#include "stmt .h" 

#include "symbolta.h" 
#include "tempbkpt.h" 


typedef int Outc 
#define user_fai 
#define failure 
#define success 


ome; 
lure -1 
@ 
1 


class Declaration; 


class DiFile; 
class EventMgr; 
class ExecSpec; 
class ExprObj; 
class StackFrame 
class Status; 
class Thread; 


enum PSA1 { psal 


psai_replace_breakop, 


psal_rep 
};: 


_hone, 


lace_libpt, 


enum PSA2 { psa_none, 
psa_run_to_retaddr, 
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class Process 
Key key; 
Thread * current; 
LinkList threadlist; 
TempBkptMgr tempbkptmgr; 
EventMgr * eventmgr; 
MemAccess memaccess; 
Disassembler 
Symboltable symboltable; 
ModuleMgr modulemgr; 
AddrVector destvector; 
Stmt startstmt; 


(unsigned long) b.hi >> ent; 


: public ItemNumber { 


// ® in ctor 


// set in ctor 


disassembler; 


(continued on page 98) 
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Save Time, Save Money, Save Code... 


REVISION CONTROL 


A quality configuration 
management system 
can save your develop- 
ment environment from 
all kinds of disasters. 
Avoid costly collisions, 
keep a complete audit 
trail, and automatically 
rebuild your project — 
saving time, saving 
money and even saving 
you from potential 


“environmental disaster.” 


When you're looking for 
a quality configuration 
management system, 
you want the best in 

the business. 


MKS RCS (Revision 


Save Your Environment 








reliable, easy to use, and 
a reputation for excel- 
lence make MKS RCS 
the best in the business. 


@ our Windows GUI 
saves valuable time — get 
up and running quickly 


@ MKS Make performs 
precise, uniform, repeat- 
able builds of your project 


™ designed for use by 
teams on networks; spe- 
cialized support for Novell 


@ unlimited branching 
and merging, locking, 
binary file support, 
access lists 


SYSTEM 


“MKS gave us the 
solution we needed 


uct at the best price. 
Save thousands of dol- 


lars by choosing MKS! across platforms” 
Lotus Development 

@ Platforms Supported Corporation 

=DOS = WINDOWS “MKS RCS has easily 

" UNIX = WINDOWS NT paid for itself with 

® OS/2. = & MORE 


the time it has saved 
our engineers” 


MKS ha tation 
2 onepeor Glenn Lewis, Intel 


for excellence — quality 
software, prompt 
support, real value. 

At MKS the customer 
always comes first. Join 
IBM, Lotus, Intel, DEC, 
Hewlett Packard... and 
choose MKS as your 
partner in innovation. 


35 King Street North, }§& 
Waterloo, Ontario ec 
Canada N2J 2W9 

Tel: (519) 884-2251 


Continental 

U.S.A. & Canada: 
800 - 265 -2797 

Fax: (519) 884-8861 
inquiry @ mks.com 
CompuServe: 73260, 1043 


MKS 


MORTICE KERN SYSTEMS INC. 


Control System) is that 
system. Fully featured, 


Complete satisfaction or 
money-back guarantee. 


@ we believe in giving 
our clients the best prod- 


Call in for your free copy of “Saving Time and Money with Configuration Management’. 


Australia +61 03 580 1333 - Belgium +32 02 732 4020 / +32 010 611 919 - Denmark +45 45 87 7200 00 - Finland +358 90 506 2600 - France +33 1 48 77 22 44 / +33 1 39 46 16 16+ 
Germany +49 0721 988 280 / +49 0551 507 620 = Italy +39 02 4801 6053 / +39 02 4819 3440 - Japan +81 03 3293 4711 + Korea +82 02 561 1021 3 - Netherlands +31 020 614 2463 - Norway +47 22 1109 50+ 
Singapore +65 747 2266 - Sweden +46 013 11 15 88 - Switzerland +41 061 421 3201 - United Kingdom +44 084 427 5175 / +44 071 833 1022 / +44 036 465 4100/ +44 078 855 2005 


CIRCLE NO. 168 ON READER SERVICE CARD 











Application developers and IS managers flock to meet industry experts, touch 
base with over 250 tool vendors and interact with 25,000 of their peers. 


a 





‘*“A fantastic conference! 
The ONLY show developers 


should attend.”’ 


Brian Francis 
Software Engineer 
Harbinger EDI Services 


oftware Development ’94 and 

Business Software Solutions, 

the leading event for builders 
and integrators of software for the 
enterprise is set for the San Jose Con- 
vention Center, San Jose, California, 
the week of March 14-18, 1994. 


By now most developers have probably 
heard about the excitement Software 
Development conferences and shows 
generate. Last February’s event in Santa 
Clara, California, brought together 
more than 10,000 leaders in the devel- 
opment community. 


I was able to get 


SEVERAL EVENTS AT ONE PLACE AND TIME 

his year Software Devel- 
opment ‘94 _ offers 
expanded ways for 





developers to learn more about impor- 
tant new development products and 
technologies. In addition to the multi- 
tude of peripheral events that are 
always a part of SD, new tracks 
have been added to the curricu- 
lum and an entirely new confer- 
ence and exhibition has been 
launched to run concurrent with 
SD at the San Jose Convention 
Center this March. 


Business Software Solutions, the 
technical event for builders and 
integrators of software solutions 


Serious Fun 


SPECIAL EVENTS BRING ADDED VALUE 
TO PARTICIPANTS 

oftware Development/Busi- 
ness Software Solutions is the 





only place to hear from 
industry movers and shakers “up close 
and personal.” The following list of 
special events is just the beginning of 
what is being planned by vendors, 
SIG’s, associations and other industry 
groups. 


PRODUCT LAUNCHES 

istorically, SD has been 

the venue for major 

product launches in 
the desktop development market. 
Microsoft’s dramatic unveiling of Visu- 
al C++ with a full symphony in Santa 
Clara this past February is just one 
example. Borland also launched their 
C++ for OS/2. Symantec launched 
C++ 6.0 at last summer’s Boston edi- 
tion. Attendees to the March event will 
be in the front row for the best new 
offerings for 1994. 


As we go to press, Borland, Power- 
soft/WATCOM, and Symantec have 
locked up Tuesday, Wednesday and 
Thursday nights for unveiling new 
product information and more of the 
famous SD parties . 


something I could use back at my 
shop from every class I 
attended....This conference is an 
excellent investment of my 

time and my 99 

company’s dollars. 


D. Andre Bakken 
Product Manaager 
Great Plains Software 


for the enterprise, has been 
launched out of the former Win- 
dows & OS/2 Conference. 
Together with an executive-level 
conference called Managing Soft- 
ware & Development, the three 
conferences offer just the right 
informational mix for anyone 
involved in developing software 
for the desktop. 














FREE TECHNICAL SESSIONS 
Powersoft * Microsoft * The Prolog 
Vendors Group * Computer Associates 


New This March 

LUNCH HOUR PANELS 

Don’t miss these provocative panels 
held during lunch: 

¢ Multimedia Development 

¢ Computer-Telephone Integration (CTI) 


AND SO MUCH MORE... 

Even more events are in the works for 
the most important event for desktop 
developers, including the Keynote 
Address, the Jolt Cola Product Awards, 
and the RAD Contest. Call today for 
your FREE ticket — a $50 Value — which 
gains you admission to all these events 
plus more at Software Development ‘94 
and Business Software Solutions. 





e Hackers vs. Security 


The Bigvest and Best Tools Exhibition Ever! | 


Access all the major industry players in one place, af one time. More than 250 of the leading language and tool vendors will be on hand to update the development 
community with their latest product news. The exhibit floor is a highly charged arena where show-only attendees interact with their peers who build the tools they need. With 
the addition of the concurrent Business Software Solutions product exhibition, professional developers will be able to preview a broader range of tools categories than ever 
before. These include more visual development tools and a variety of vendors offering sophistocated client/server solutions software. 
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EVENING EXCITEMENT 


ake - advantage of 


The widest varity of course 


Reap the Benefits 





enlightening evening the industry. Exposure to 

sessions. Some of the veryone in the some of the best é 
hot topics you can participate in development field products on the market. 
include: “The Current State of Object can benefit by taking Todd Stuart 


Sr. Programmer Analyst 


part in the live discussions, tech- UNUM Life Insurance 


Standards” moderated by Paul Har- 


offerings by the greatest minds in 


mon of Harmon Associates and Robert 
Spurgeon of Andersen Consulting; 
“Cross Platform Development Direc- 
tions” moderated by Melanie 
McMullen of LAN Magazine; “Desktop 
Development for the “90s: Operating 
System Directions” moderated by Brett 
Glass of InfoWorld; “What’s Hot, 
What’s Not in Software” moderated by 
Randy Dugger of Tandem Computer; 
“Development Tool Shoot-Out: 3GL 
vs. 4GL moderated by Kathy Auerbach 
of Century Market Research; and 
“PowerPC Development” moderated 


nology exchanges and 
debates that make up 
Software Development °94 
and Business Software 
Solutions. Take part in 
over 200 educational ses- 
sions, see products up 
close from over 250 key 
tool vendors, and hob 
nob with 25,000 of your 
peers. Come and be 
educated, as well as 
entertained! 


SOFTWAR 


Ve 


Os ee 


This industry event offers 200+ educational sessions 


and the sa Ml to view the lasted products from 


by Neil Tickton of MacTech Magazine. 


more than 250 strategic vendors. 








DESIGN 


Listing Three (Listing continued, text begins on page 40.) 


Outcome start_stmt_step_into( Thread * ); 
Boolean now_executing; Outcome start_stmt_step_over( Thread * ); 
DiFile * target_difile; public: 
PSA1 psal; Process( unsigned int, DiFile * ); 
PSA2 psa2; ~Process(); 
char *current_lang; // Temporary hack to be able 

to set the language. Outcome get_status( Status & ); 

Thread * lookup_thread( unsigned int ); Outcome wait_status( Status & ); 

Outcome update_status( const Status & ); 
Outcome check_state(); Boolean is_executing() { return now_executing; } 
Outcome set_execspec( const ExecSpec & ); 
Boolean goal_attained(); Outcome run( const ExecSpec & ); 

Outcome instr_step_into( const ExecSpec & ); 
Outcome start_step_into( Thread * ); Outcome instr_step_over( const ExecSpec & ); 
Outcome start_step_over( Thread * ); Outcome stmt_step_into( const ExecSpec & ); 
Outcome start_step_retaddr( Thread * ); Outcome stmt_step_over( const ExecSpec & ); 
Outcome start_run( Thread * ); Outcome resume (); 

Outcome stop(); 
Outcome analyse_stmt_into( Boolean & ); 
Outcome analyse_stmt_over( Boolean & ); Thread * current_thread() { return current; } 


Outcome run_to_return_addr( Thread * ); Outcome disassemble( const Addr &, Instruction &, Addr & ); 
Outcome execute_to_return_addr( Thread * ); Outcome find_stmt( const Addr &, Stmt & ); 
Outcome run_to_caller( Thread * ); Outcome find_function( const Addr &, Declaration & ); 


Outcome end_instr_step_into( Thread * ); Outcome evaluate( char *, StackFrame & ExprObj & ); 
Outcome end_instr_step_over( Thread * ); Outcome set_language(char *input_language) ; 
Outcome end_stmt_step_into( Thread * ); char *get_lang_string(); 

Outcome end_stmt_step_over( Thread * ); Process * next() { return (Process *)Item::get_next(); } 
Outcome end_run( Thread * ); a3 
#endif 

Outcome check_instr_step_into( Thread * ); * at 
Outcome check_instr_step_over( Thread * ); End Listings 
Outcome check_stmt_step_into( Thread * ); 

Outcome check_stmt_step_over( Thread * ); 

Outcome check_run( Thread * ); 


Outcome respond_to_hop_completion( Thread * ); 
Outcome respond_to_retpoint( Thread * ); 
Outcome respond_to_destpoint( Thread * ); 
Outcome respond_to_breakpoint( Thread * ); 
Outcome respond_to_watchpoint( Thread * ); 
Outcome respond_to_exception( Thread * ); 
Outcome respond_to_step_completion( Thread * ); 
Outcome respond_to_suspension( Thread * ); 
Outcome respond_to_exec( Thread *, DiFile * ); 
Outcome respond_to_libpt( Thread * ); 


Outcome respond_to_module_load( const Status & ); 
Outcome respond_to_module_unload( const Status & ); 
Outcome respond_to_thread_creation( const Status & ); 
Outcome respond_to_thread_destruction( const Status & ); 












has retired the old 
standard for 
tracking bugs. 








Archimedes BugBase - D'\BUGBASE\SAMPLE.BUG 


wave g %,. to pet : 
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Guventaaate ade naoa deck 


BUGBASE™ FOR WINDOWS” - THE 
PROFESSIONAL SOFTWARE DEFECT 
TRACKING TOOL. 


e GENERATE POWERFUL REPORTS & GRAPHS 
° IMPORT/EXPORT /MERGE DATABASES 
© CUSTOMIZE THE SETUP TO YOUR NEEDS 
e NETWORK SUPPORT 





FOR MORE INFORMATION, CALL: 
“At a glance, you can tell the status of any defect or 415-567-4010 





change order, who is responsible for correcting the IN EUROPE, CALL: + 47 67 15 67 OO ARCHIMEDES 
defect or implementing the change, and when the FAX: + 47 67 15 67 O1 SOFTWARE 
updated version is expected.” Archimedes Software, Inc. 2159 Union Street, San Francisco, CA 94123 
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_ Itruns with 


NetWare 
Developer tested. 


® 


LISTED ACCESSORY 


6C61 


Some Magic Words to Help Software 


Developers Increase Their Revenues 


In every successful software product 
there is a spark of magic. That magic 
brings together the ingenuity, skill and 
years of hard work you’ve invested 

in developing something unique and 
valuable. 


Trouble is, the worldwide epidemic of 
software piracy threatens your 
investment. By draining potential 
revenues, the illegal use of software 
dramatically reduces your profit margins. 


Aladdin’s business is helping software 
companies protect their products — and 
their profits. 


Since 1984, over 8,000 developers in more 
than 60 countries have chosen HASP °— 
the Professional Software Protection 
System — to increase their revenues. 


HASP ® delivers the highest level of 
security for developers, without 
inconveniencing legitimate users. 
Experts recognize its design as the most 
technologically advanced software 
protection product on the market. 


That’s our 
magic. 


Call now for your ™ 
HASP® evaluation kit. 


ALADD 


SOFTWARE SECURITY INC 


North The Empire State Building 
America 350 Fifth Avenue, Suite 7204 
New York, NY 10118, USA 
Tel: (800) 223 4277 
212-564 5678 
Fax: 212-564 3377 


International Aladdin 

Office Knowledge Systems Ltd. 
15 Beit Oved St., Tel Aviv, Israel 
P.O.Box 11141, Tel Aviv 61110 
Tel: 972-3-5375795 
Fax: 972-3-5375796 
AppleLink: ALADDIN.KNOW 
Compuserve: 100274,434 


France Aladdin France SA 
Tel: 33 1 40 85 98 85 
Fax: 33 1 41 2190 56 


Systems Ltd. 1985-1994 (7.94) 


© Aladdin Knowle 


®@ Australia Conlab 3 8985685 M@ Belgium Akkermans 3 2338826 MM Czech ATLAS 2 766085 M Chile Micrologica 2 222 1388 
H Denmark SC Metric 42 804200 @ Finland ID-Systems 0 870 3520 M Germany CSS 201 7498640 MM Greece Unibrain 1 6856320 
B Holland Akkermans 45 241444 W® Italy Partner Data 2 26147380 MH Japan Athena, 3 58 213284 M Korea Dae-A 2 848 4481 
lH New Zealand Training , 4 5666014 M@ Poland Systherm 61 475065 M Portugal Futurmatica 1 4116269 @® South Africa D Le Roux, 11 886 4704 
®@ Spain PC Hardware, 3 4493193 Mi Switzerland Opag 61 7112245 @ Taiwan Teco 2-555 9676 & Turkey Mikrobeta 4-4677504 
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PROGRAMMER'S WORKBENCH 


e e ° 
Listing One (Text begins on page 82.) } // LBN_SELCHANGE end 
} // select on notification code end 
PTTL ILC LLCO LCCCLCCLeCreerrereettreteteretrettretretereteetre errr Let. 9) } // select on control id end 
/* CLIENT.C -- Database client program (Windows app). By Walter Oney */ break; 
PITTI T ILC LLCCLCCCCLCCCCLeeererrettetereeretrttr tt te ter trrrertrr crete Sy) case WM_DESTROY: 
if (bRegistered) 
#include <windows.h> { int code; // close out WINGate connection 
#include <windowsx.h> WGTRANS trans = WGCreateTrans("client", @); 
#include <string.h> WGSetTransValue(trans, 1, 0); 
#include <wingate.h> WGExecute(trans, "server", 10@@, WG_STAT_NO_RESPONSE, &code); 
WGDestroyTrans (trans) ; 
static HINSTANCE hInst; WGUnregisterClient ("client") ; 
} // close out WINGate connection end 
LRESULT CALLBACK MainWndProc(HWND, UINT, WPARAM, LPARAM) ; PostQuitMessage(@) ; 
break; 
#define arraysize(p) (sizeof(p)/sizeof((p) [@])) default: 
DEGRASSI ACSA IGG CG IGRI CGIGCGGCGGR GORGE A RA kkk / return DefWindowProc (hwnd, msg, wParam, 1Param); 
int NEAR PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrev, } // process message end 
LPSTR 1pCmd, int nShow) // WinMain return @; 
{ HWND hwnd; // main window handle } // MainWndProc end 
MSG msg; // current message 
. + + e e 
WNDCLASS we; // window class descriptor Listing Two 
if (hPrev) // only allow 1 instance at a time 
return @; GEC GSAS CISC GIES CIS IS GIR IGRI CRG CASAS ICI I KR Ik 8 ak k / 
hInst = hInstance; /%* SERVER.C -- DOS-based database server for WINGate demo. */ 
memset (&we, , sizeof(we)); /* Written by Walter Oney */ 
we.lpszClassName = "clientwindow"; GERGG ORCC OCCA OCICS Saco gra kkk a Rsk kok kkk kak / 
we. hInstance = hInstance; 
we.lpfnWndProc = MainWndProc; #include <stdio.h> 
we.hCursor = LoadCursor(NULL, IDC_ARROW) ; #include <stdlib.h> 
we.hIcon = LoadIcon(NULL, IDI_APPLICATION) ; #include <wingate.h> 
we.hbrBackground = (HBRUSH) (COLOR_WINDOW + 1); static void error(int code); 
if (!RegisterClass (&wc) ) 
return Q; 
hwnd = CreateWindow("clientwindow", "WINGate Database Demonstration", #define arraysize(p) (sizeof(p)/sizeof((p) [@])) 
WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, ECC CECE CGO CISC CIS CIGARS CG GCG Ia KR k ak kkk / 
CW_USEDEFAULT, @, NULL, hInstance, NULL); void main() // main 
if (!hwnd) { short code; // error code 
return Q; if ((code = WGInit(@, 16384))) 
ShowWindow(hwnd, nShow) ; error (code) ; 
if ((code = WGRegisterServer("server", 1024, @, @))) 
while (GetMessage(&msg, 0, 9, O)) { // can't register server 
{ // process messages WGTerm() ; 
TranslateMessage (&msg) ; error (code) ; 
DispatchMessage(&msg) ; } 
// process messages end while (1) // until told to quit 
return msg.wParam; { WGTRANS trans = WGGetTrans(); 
} // WinMain end if (trans) // process transaction 
ERR ACIE CGS E CGI GI CCGG CASSIS GEG ASCII CIR I IK Ra ak kk kak / { char country [8@]; // name of country being queried 
LRESULT CALLBACK MainWndProc (HWND hwnd,UINT msg,WPARAM wParam,LPARAM 1Param) int i; // loop index 
{ // MainWndProc long tid; // transaction id 
static char *country[] = WGTRANS response; // response to query 
{ "“Afghanistan","Algeria","Angola","Argentina", "Australia", "Austria" static char *key[] = 
yi 
static HWND hwndList; // list of countries "Afghanistan", "Algeria", "Angola", "Argentina", 
static BOOL bRegistered; // TRUE if registered with WINGate "Australia", "Austria" 
switch (msg) // process message }; 
{ case WM_CREATE: // WM_CREATE static char *value[] = 
{. ant 2s { 
if (WGRegisterClient ("client") ) "Kabul", "Algiers", "Luanda", "Buenos Aires", 
{ // couldn't initialize WINGate "Canberra", "Vienna" 
MessageBox(hwnd, "Unable to initialize WINGate", "ERROR", }; 
MB_OK | MB_ICONHAND) ; tid = WGGetTransID(trans, &code) ; 
return -1; if (WGGetTransValue(trans, 1, &code) == @) 
} // couldn't initialize WINGate break; // error or "quit" request 
bRegistered = TRUE; WGGetTransString(trans, country, sizeof(country)) ; 
hwndList = CreateWindow("listbox", "", for (i = 0; i < arraysize(country); ++i) 
WS_CHILD | WS_VISIBLE | WS_VSCROLL | LBS_NOTIFY, if (stremp(country, key[i]) == 0) 
®, ®, ®, 0, hwnd, (HMENU) 100, hInst, NULL); break; // found it 
if (!hwndList) response = WGCreateTrans("server", strlen(value[i])+1); 
return -1; WGSetTransString(response, value[i]); 
for (i = @; i < arraysize(country); ++i) WGPostResponse(response, tid); 
ListBox_AddString(hwndList, country[i]); WGDestroyTrans (response) ; 
break; } // process transaction end 
} // WM_CREATE end _asm // yield time slice 
case WM_SIZE: { mov ax, 168@h 
{ RECT rc; // WM_SIZE int 2Fh 
GetClientRect (hwnd, &rc); i ; // yield time slice end 
if (hwndList) }  // until told to quit 
MoveWindow(hwndList, re.left, re.top, re.right-re.left, WGUnregisterServer ("server") ; 
re.bottom-rce.top, TRUE) ; WGTerm() ; 
break; } // main end 
} // WM_SIZE end PREGGO RCC GCC CCCCI SGC SCC ICSC GSAS IG SESSA G SIG Ia I I Rak ak kak ok / 
case WM_COMMAND: static void error(int code) 
switch (LOWORD (wParam) ) // select on control id { // error 
{ case 100: // the list box printf("WINGate error %d\n", code); 
exit(1); 
switch (HIWORD(1Param) ) // select on notification code } // error end 
{ ar 
case LBN_SELCHANGE: // UBN_SELCHANGE End Listings 
{ char msgbuf [89] ; // message assembly buffer 
int i: // selection (country) index 
char capital [8]; // response from server 
WGTRANS trans; // query transaction 
int code; // error code 
long tid; // query transaction id 


i = ListBox_GetCurSel (hwndList) ; 

trans = WGCreateTrans("client", 8@); 

WGSetTransString(trans, country[i]); 

WGSetTransValue(trans, 1, 1); 

tid = WGExecute(trans, "server", 1000, 
WG_STAT_WAIT_RESPONSE, &code) ; 

WGGetResponse(trans, tid, WG_STAT_WAIT_RESPONSE) ; 

WGGetTransString(trans, capital, sizeof(capital)); 

WGDestroyTrans(trans) ; 

wsprintf(msgbuf, "The capital of %s is %s", 
(LPSTR) country[i], (LPSTR) capital); 

MessageBox (hwnd, msgbuf, "Geographical Information", 
MB_OK | MB_ICONINFORMATION) ; 

break; 
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fé Modify time of object file associated with heap. when a heap is 
#e archived, the object stamp is set to zero, unless the heap was opened 
/? for update. 
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class SiennaVisiter : public Sienna_Walker { 
public: 
/é This class defines a generic Sienna tree walker. 
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éf The Source Region data structure defines a contiquous 
#f source file, The Start and End positions of a Source 
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struct Tn Sublist ¢ 
Tn Child Left: 
Tn Child Right: 
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Writing Non-SCSI 
CD-ROM Device Drivers 





Sing Li 


ne advantage of SCSI interfaces is 
| their high data-transfer rate — any- 
; where from 5 to 20+ Mbytes/sec- 
ond. But when you consider the 
300 Kbytes/second data-transfer rate typ- 
ical of CD-ROM drives, you wonder, 
“Why bother?” The answer is, of course, 
compatibility. Although usually more ex- 
pensive and often slower, standard inter- 
faces such as SCSI do allow you to mix- 
and-match CD-ROM drives. Software 
development is also easier because you 
only support one standard. This explains, 
in part, why the initial release of Microsoft 
Windows NT and IBM OS/2 2.x only sup- 
ported SCSI-based CD-ROM hardware. 

However, there are still times when 
you'll want to use non-SCSI CD-ROM 
drives with these operating systems. For 
one thing, non-SCSI CD-ROM drives of- 
ten sell for several hundred dollars less 
than their SCSI cousins. In other in- 
stances, you may already have a num- 
ber of proprietary-interface drives and 
may not want to reinvest in new ones 
that provide essentially the same capa- 
bilities. Whatever the case, I'll present 
in this article a non-SCSI CD-ROM de- 
vice driver for NT. But first, some back- 
ground on CD-ROM formats and NT de- 
vice drivers. 









The author is a product architect with 
Media Synergy in Toronto. He develops 
for embedded systems, GUI portability 
platforms, and device drivers. You 
can contact him at 70214.34600@ 
compuserve.com. 
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CD Physical and Logical Format 

The physical format of audio CDs (de- 
tailed in the “Red Book” from Philips) 
is commonly referred to as the “CD-DA,” 
or compact-disc digital-audio format. A 
CD-DA disc is divided into sectors, each 
containing 2352 bytes of audio data. Ad- 
ditionally, each sector contains 784 bytes 
of error-correction data and 98 control 
bytes. On all CD drives, these 784+98 
bytes are handled exclusively by the 
read hardware. 

During audio play of all audio CD 
drives and most CD-ROM drives, Red 
Book audio data is fed directly to de- 
coding digital-to-analog conversion 
hardware. Consequently, direct com- 
puter reading of Red Book audio from 
audio CDs usually isn’t possible. Some 
CD-ROM drive manufacturers make 
drives capable of directly accessing Red 
Book audio. This gives you the capa- 
bility to enhance, manipulate, and edit 
commercial music. 

While the Red Book describes the 
CD-DA format, the “Yellow Book” from 
Philips/Sony describes the recording for- 
mat for digital computer data on CD- 
ROMs. Data on Yellow Book sectors is 
laid out in two “modes” based on the 
2352 data bytes available on a CD-DA 
sector. Most currently available CD-ROM 
titles are recorded in Mode 1, which 
specifies 2048 bytes of user data, 288 
bytes of error-detection/correction data, 
and 16 bytes of synchronization and 
header information; see Figure 1(a). 
Mode 1 sectors can be recorded on a 
disc containing CD-DA audio—a 
“mixed-mode disc.” The first “audio 









(a) 1 
bytes 


6 bytes Sync Header + 2048 bytes User Data + 288 bytes EDC/ECC data = 2352 | 


(b) 16 bytes Sync Header + 2336 bytes User Data = 2352 bytes 
(c) 8 bytes subheader + 2048 bytes data + 289 EDC/ECC data = 2336 bytes 


(d) 8 bytes subheader + 2324 bytes data + 4 bytes EDC data = 2336 bytes 


track” of a mixed-mode disc is reserved 
for computer data recorded in Yellow 
Book Mode 1 sectors. Many popular 
multimedia titles, including Loom, 7th 
Guest, and Just Grandma and Me, use 
mixed-mode format to incorporate pro- 
fessionally recorded, stereo-CD audio 
tracks. 

Mode 2 format is the base format for 
CD XA (Extended Architecture) discs. 
With this mode, 2336 bytes are avail- 
able for user data on each sector. This 
means that the 288 bytes of Mode 1 er- 
ror detection/correction is removed. 
Since the chance of uncorrectable error 
is higher, this mode is seldom used for 
raw computer data. Potentially, it can 
be used to store raw audio, image, or 
video information in which single-bit 
errors aren't critical. The XA format 
builds on this mode, making it more ro- 
bust for handling data; see Figure 1(b). 

The CD XA specification, specifically 
designed for multimedia, is an extension 
to the Yellow Book, although currently 
hardware which can handle the standard 
is lacking (CD-ROM drives and con- 
trollers). In the future, Kodak Photo CD, 
Philips Video CD, and the MPC 2 stan- 
dard may create more demands for CD- 
ROM titles recorded in XA format. On 
top of a Yellow Book Mode 2 sector, the 
CD XA standard can record data onto 
the 2336 available user data bytes in two 
different forms. Form 1 has 2048 bytes 
of data, with an 8-byte leading sub- 
header, and 280 bytes of error-detec- 
tion/correction information; see Figure 
1(c). Form 1 is typically used for storing 
computer data on XA discs and is sim- 
















Figure 1: (a) Yellow Book Mode 1 Sector; (b) Yellow Book Mode 2 Sector: 


(c) CD XA Form 1; (d) CD XA Form 2. 
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(continued from page 102) 
ilar to the Mode 1 format, with 2048 
bytes of error-corrected data. The Form 
2 specification replaces the 280 bytes 
EDC/ECC of Form 1 with only four bytes 
of error-detection data; see Figure 1(d). 
Lacking robust error-correction capabil- 
ities, Form 2 sectors are typically used 
for audio or video data only. The XA 
standard calls for ADPCM compression 
of audio data, and the playback is usu- 
ally assisted by decoding hardware. 
On an actual XA CD disc, Form 1 and 
Form 2 sectors can be interleaved — this 


CD-ROM 


is the XA’s key advantage for multimedia 
applications. XA provides for interleaving 
of data with audio or video, allowing 
playback of high-quality multimedia 
content directly off the CD-ROM with- 
out expensive hardware configurations. 
Distinction between sectors of the two 
forms is typically handled via hardware 
by scanning the 8-byte subheader. 
Since Mode 1, Mode 2, and XA sec- 
tors are based on the Red Book sector 
format, it’s theoretically possible to use 
an audio CD mechanism for CD-ROM 
purposes. Some early CD-ROM drives 
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took advantage of this. These designs 
quickly became obsolete because of the 
slow audio-mechanism access time (typ- 
ically 600 milliseconds to 1 second) and 
the intensive software decoding neces- 
sary to extract data. Almost all CD-ROM 
drives use custom-designed CD-ROM 
mechanisms with fast seek times and 
hardware data detection. 

The logical format of a CD-ROM spec- 
ifies how files and directory structures 
are laid out over the physical sectors. 
The most commonly used logical format 
is the ISO-9660 standard. As a cross-plat- 
form standard, ISO-9660 CD-ROMs can 
be read by DOS, Macintosh, VMS, and 
UNIX workstations. Consequently, ISO- 
9660 inherits all the restrictions of the 
differing file systems, the most severe 
being the eight-character filename and 
eight-level directory restrictions. Since 
this is especially troublesome for UNIX, 
several UNIX-based companies have pro- 
posed an extension to ISO-9660 stan- 
dard— the Rock Ridge Extensions. (For 
more on the Rock Ridge Extensions, see 
Lynne Jolitz’s “Extending Standards for 
CD-ROM” in the July 1993 issue of DD/) 

Full ISO-9660 provides enhancements 
including security, multivolume sets, and 
multiple-extent files Ginterleaving). In 
practice, most operating-system exten- 
sions (such as MSCDEX on MS-DOS) 
don’t currently support these features. 
Consequently, few published CD-ROM 
titles use these enhancements. 

Kodak introduced the Photo CD as 
its flagship product in the popular dig- 
ital photography market. Anyone can 
get up to 100 photo prints stored on a 
digital Photo CD. Each picture is stored 
in six different resolutions, the highest 
approaching the definition of the orig- 
inal 35mm negative. Besides direct view- 
ing of the photos on television, Photo 
CD can also be used to make prints and 
even to recreate the original negative. 
Photo CD discs can be read on XA-com- 
patible CD-ROM drives, Philips CD-I sys- 
tems, or consumer Photo CD players. 

The Kodak Photo CD format is com- 
patible with the CD XA specifications. 
The actual format is called “CD-I 
Bridge,” and it is proprietary to Philips 
and its licensees. Photographs are dig- 
itized via high-resolution scanners and 
stored on the Photo CD in ISO-9660 for- 
mat over CD XA Mode 2 Form 1 sec- 
tors. The actual disc medium is a 
writable compact disc. Unlike injection- 
molded “silver” CD-ROMs, Kodak Pho- 
to CDs are made with a gold substrate 
on pregrooved discs writable via a 
modulated high-power laser beam. 

Multisessions allow you to add new 
files (photos) to the write-once medium 
each time you bring the Photo CD back 
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to your photo finisher. Since the medium 
is not rewritable, the directory structure 
of the original disc can’t be changed. 
However, on a multisessions Photo CD, 
a new directory structure of the entire 
disc is created as each new session is 
written to the disc. Multisessions- 
compatible CD-ROM drives will always 
seek and use the latest directory struc- 
ture when referring to the content of the 
disc. Noncompatible drives will be able 
to read only the content of the original 
single session. 


NT Device Drivers 

As Figure 2 illustrates, NT is a layered, 
packet-driven system in which every 
I/O request is represented as an I/O re- 
quest packet. Since NT supports multi- 
ple operating-system environments via 
subsystems, I/O must be flexible and 
generic enough to handle demands from 
native NT, 16-bit Windows, DOS, OS/2, 
and POSIX applications. 

To simplify device-driver design for 
layered device drivers, NT uses Filter, 
Class, Port, and Miniport drivers. De- 
vices such as CD-ROM drives have com- 
mon requirements which can be ab- 
stracted. The only code that absolutely 
needs to be rewritten for each device is 
the device-specific commands and pro- 
tocol handling. Under NT, monolithic 
drivers (which handle a single device 


Access Hardware a 





Figure 2: NT I/O architecture. 
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each requiring its own specific driver 
code) can be divided into cooperating- 
operating driver layers. For example, to 
control a SCSI] CD-ROM device, you 
have a SCSI CD-ROM Class driver that 
handles generic, data-related CD oper- 
ation common to all CD-ROM drives. 
To perform its task, the SCSI CD-ROM 
Class driver calls on the SCSI Port driv- 
er, which provides a high-level generic 
SCSI command send/retrieval interface, 
shielding any adapter-specific details 
from the Class driver. The Port driver 
also understands the SCSI protocol and 
its implementation. To control the de- 
vice through a SCSI bus, the Port driv- 
er calls on the adapter-specific SCSI 
Miniport to implement the low-level 
send, signal control, and synchroniza- 
tion tasks that must be individually de- 
signed for each adapter. Additionally, 
the SCSI Miniport driver makes use of 
services provided by the SCSI Port driv- 
er to carry out its duties. In this way, 
the SCSI Miniport is wrapped and will 
be transparent to changes within the 
SCSI Port driver and the operating sys- 
tem. Figure 3 illustrates the relationship 
between the layered drivers. 

The SCSI Port and Miniport driver 
stack can service any SCSI device oth- 
er than CD-ROM, including hard disks, 
tapes, and the like. The CD-ROM driv- 
er only has to be written once for any 
f SCSI CD-ROM drive and 








Indexes of 


Dr. Dobb’s 
JOURNAL 


1982-1993 


¢ Cumulative Subject and 
Author Indexes covering the 
years 1982 through 1993, 
bound in ONE volume. 


e An 8" X11" paperback with 
136 pages and 9300 entries. 


¢ Detailed coverage of all 
editorial material, including 
reviews, letters, tables, 
sidebars, bug reports, 
corrections, etc. 


¢ Find that article, program, 
product review, algorithm, or 
routine (by language or type) 
in seconds, or follow the 
threads of a technical 
conversation. 


¢ Hypertext version available 
on 3.5" disk (DOS). 


BOOK: $21.95 ppd 
(Canada $22.85 U.S.) 


DISK: $14.95 ppd 
(Canada $15.70 U.S.) 
VISA/MC 


Previous purchasers of the diskette 
version may purchase the latest edition 
for $10.00 (Canada: $10.85 U.S.). 


Voice/Fax: 


804-977-7015 


Stephen Bach 
1411 A Short 18th Street 
Charlottesville, VA 22902-5402 


Please specify 5" or 3" when ordering. For shipping paper- 
back edition via first class mail add $1.75 
(Canada $2.00 U.S.). 





105 


CD-ROM 





come a de facto standard, and most CD- 
ROM devices comply with it. Extension 
commands (such as audio control, multi- 
. | | | session handling, and so forth) are a dif- 
P . ferent story, as most drive manufactur- 
| ers have their own _ extensions. 
Fortunately, the SCSI CD-ROM Class driv- 
er can handle this. However, this requires 
modifying the SCSI CD-ROM Class driv- 
er each time a new drive type is added. 
This approach is impractical since Mi- 
crosoft retains ownership of the SCSI 
CD-ROM Class driver under NT. Thus 
was born the “CDAudio Filter driver,” a 
collection of exceptions implemented as 
a middle-layer device driver and pre- 
sented in this article. The function of the 
Filter driver (which sits between the I/O 
manager and the SCSI CD-ROM Class 
driver) is to recognize and intercept any 
device-specific commands and process 
them without passing them to the SCSI 
CD-ROM driver. 

The upcoming SCSI 2 addresses the 
audio-control problem by providing 
, i audio-control commands. This means 
Figure 3: The layered NT device driver. that SCSI 2-compliant CD-ROM drives 

will respond to the same set of audio- 
adapter. In actual implementation, each | comes to nondata command handling. | control commands, allowing implemen- 
SCSI CD-ROM drive may have its own Since the SCSI interface was designed | tation of such extension in the SCSI Port 
unique features not found in other de- | to handle storage devices, the storage- | driver and freeing the SCSI CD-ROM 
vices. This is especially true when it | device management command has be- | Class or the CDAudio Filter. 
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The most obvious approach (and that 
recommended by Microsoft) is to hook 
into the layers at the lowest level. This 
means writing a Miniport driver to re- 
ceive the SCSI command, decode it, han- 
dle the request, repackage the response 
into SCSI status blocks, and transmit it 
back to a SCSI Port driver— a software 
emulation of a SCSI adapter. While in- 


Full ISO-9660 
provides security, 
multivolume sets, 

and multiple-extent 


files 


efficient, this approach does have the 
advantage of operating-system inde- 
pendence. This is the approach I'll de- 
scribe here. 





The Driver Program 

This driver handles data-read operations 
for ISO-9660 Mode 1 discs and is suffi- 
cient for installing Windows NT from 
the distribution CD-ROM. For this pur- 
pose, the driver will also assume that 
the CD-ROM is inserted into the drive 
before the driver is started, and that 
there'll be no CD changes during the 
operation of the driver. 

The Windows NT installation proce- 
dure consists of an initial text setup dur- 
ing which the user boots the setup flop- 
py disk, which in turns loads in the 
minimal keyboard, mouse, video, ma- 
chine/HAL, disk, and SCSI drivers. This 
is where you install this CD-ROM driver. 
TXTSETUP.OEM, the file which pro- 
vides the NT setup program with infor- 
mation concerning the Miniport driver, 
is an ASCII script file included with the 
Windows NT DDK. 

Once the drivers are loaded, the set- 
up procedure lets you prepare the hard 
disk and select location for installation 
of Windows NT. After this, the setup 
program copies a working set of files 
from the CD onto the Windows NT par- 
tition. My CD-ROM driver will also be 
copied during this process. Upon com- 
pletion, the hard-disk version of Win- 
dows NT can be booted to continue the 
second phase of installation where NT 
is booted from the hard disk and the 
driver is loaded in the operating system. 
The setup program then prompts you 
to select the remaining installation op- 
tion. Finally, the rest of the NT system 
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Base Port 


Base Port+1 
Base Port+2 
Base Port+3 


Data register 
Not used 


Status code register 
Hardware status bits 


CD-ROM 


Command register 
Not used 

Hard reset 
Configuration 





Table 1: Panasonic CD-ROM drive I/O port registers. 


files are copied from the CD onto the 
hard disk. 

The driver consists of CDNOW.C, (List- 
ing One, page 110) which contains com- 
mon device-independent code identical 
to drivers on any CD-ROM drive, and 
CDREAD.C, which contains code spe- 
cific to the drive. In this case, the code 
is specific to the Panasonic/MKE CR522b 


drive. This approach isolates the code 
that must be changed when adapting the 
code for other drivers so that only CD- 
NOW.H and CDREAD.C need to be 
modified. The Panasonic CD-ROM drive 
controller is typically configured as four 
I/O port locations which map into the 
registers in Table 1. The drive and con- 
troller support only the polling mode of 
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data transfer. CDREAD.C and other rel- 
evant files and programmer notes are 
available electronically; see “Availabili- 
ty,” page 3. 

To initially determine where the drive 
is installed, the CDREAD.C routine Lo- 
cateAdapterSpecific() scans all the legal 
I/O locations, looking for the actual ad- 
dress of the drive. It then allocates the 
address from NT before accessing it, and 
frees it if the drive isn’t found at a spec- 
ified location. 

CDNOW.C contains routines which 
follow the classic SCSI Miniport format. 
Microsoft provides various Miniport 
source-code examples with the Win- 
dows NT DDK which can be used as 
reference. Since we aren’t actually deal- 
ing with an SCSI device, we will have 
to provide emulation at the appropriate 
spot. By design, we'll only deal with 
data reads; other function requests are 
left as unimplemented. 

When Windows NT loads the driver, 
DriverEntry is called. For a SCSI Mini- 
port driver, the routine initializes the 
function tables with the /nitialization( 
Startlo(), Interrupt), FindAdapter( ), 
and ResetBus() function pointers. It also 
allocates and initializes a private area 
in the device extension for storage of 
private data. The last thing the routine 
does is call ScsiPortinitialize() (sup- 
plied by the SCSI Port driver) and re- 
turn the status. 

When ScsiPortiInitialize() is called, 
the Port driver enumerates the adapters, 
resets them, and locates all the devices 
on each adapter. It does this by calling 
the functions registered in the functions 
table. FindAdapter initializes required 
system data structures, and calls find- 
AdapterPort() which in turn calls Lo- 
cateAdapterSpecific() in CDREAD.C to 
locate the adapter. 

Once the adapter is located, NT calls 
Start/O() with various SCSI requests. 
These comes in the form of SCSI Re- 
quest Blocks (SRBs). Within Startl/OQV , 
we must emulate the action of a SCSI 
host-bus adapter and a connected SCSI 
CD-ROM drive. 


SCSI Emulation 

For the purposes of this driver, it’s suf- 
ficient to handle Bus Reset, Inquiry, 
Read Capacity, and Read Data requests. 
The current Bus Reset function does 
nothing, but may be modified to reset 
the CD-ROM drive. For the Panasonic 
drive, this isn’t necessary since the drive 
is reset via hardware each time the sys- 
tem restarts. 

In handling the Inquiry request, you 
must emulate the existence of a CD-ROM 
drive at a specific SCSI target ID. In the 
emulation, the target ID of 3 is used. For 
Read Capacity requests, return a hard- 


Dr. Dobb’s Journal, March 1994 





coded capacity for a CD-ROM disc. Since 
not all drives support the read-capacity 
command, you don’t have to call Pana- 
sonic’s read-capacity command. 

For Read Data requests, ReadC’D- 
Rom() is called. This decodes the read 
request and converts it to a form usable 
by CDRead() in CDREAD.C. To keep 
the driver design simple, each read re- 
quest is completed immediately. The 
CDkRead() function issues the command, 
waits until the data becomes available, 
and fills the data buffer with the re- 
quested sector before returning. 

Every request that we handle in Start- 
Io() is completed synchronously. In sit- 
uations where interrupts and/or DMA 
are used, it’s possible to return a request 
pending status that allows the system to 
proceed with other tasks while data is 
being read. In these cases, the interrupt- 
service routine must queue a deferred- 
processing routine where the data can 
be transferred into the buffer area and 
the request packet can be completed 
via ScsiPortNotification( ). Queuing of 
request is handled by the I/O Manag- 
er/SCSI Port driver in these cases. 


Conclusion 

The driver presented here is for installing 
the operating system. To modify it for nor- 
mal data access, device-state changes must 
be tracked and handled carefully. Re- 
quests, other than data read from higher- 
level software, must also be considered. 

For example, all audio functions can 
be implemented. To track device-state 
changes, there are a total of five differ- 
ent types of popular CDs: audio only, 
data only, data and audio mixed mode, 
XA single session, and XA multisessions. 
The driver should theoretically handle 
all changes from one CD to another, as 
well as tracking changes of CD of the 
same type. This gives a total possibility 
of 120 state changes. To code a robust 
driver, all 120 cases should be handled 
and tested individually. In reality, typi- 
cal drivers handle only a couple of 
dozen cases via ad hoc design. 

SCSI Miniport emulation is only one 
way of implementing the driver. It’s also 
possible to replace the entire SCSI 
Filter/Class/Port/Miniport stack with a 
single monolithic driver, or to design 
your own CD class/IDE port/IDE mini- 
port driver stack. Such designs can be 
much more attuned to the actual hard- 
ware controlling the device. They can 
stand to gain in configuration flexibili- 
ty and performance. 


DDJ 
(Listing begins on page 110.) 


To vote for your favorite article, circle inquiry no. 15. 
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you to produce and validate a "software blueprint" of your design 
before writing a line of code. This blueprint will help prevent system 


errors, ensure commonality between project members, and facilitate 
maintenance. SELECT OMT goes beyond a traditional builder's 
blueprint, translating your design directly into C** framework code, 
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3. 
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Listing One (Text begins on page 102.) 


DESO AACA ACAI GAG CO OG ACG GGG IG IC I Kk 3k 21 21 2k a 4 
CDNOW.C -- SCSI miniport driver for Panasonic 52x using native or compatible 
controllers. Module contains general routines which are independent of 
specific drive models. 
Copyright (c) 1993 Sing Li, Media Synergy Inc. All Rights Reserved 
BEGGS GIA GSCI AIGA GGG GIG AIO ICIS I GI ROI I I OI GK a Ik ak ak kak kk / 
#include "ntddk.h" 
#include "stdarg.h" 
#include "CDnow.h" // includes scsi.h 
//****** Function ProtoTyping ****** 
USHORT 
LocateAdapterSpecific ( 
PSPECIFIC_DEVICE_EXTENSION deviceExtension, 
IN PVOID Context, 
IN OUT PPORT_CONFIGURATION_INFORMATION ConfigInfo 
ie 
BOOLEAN 
CDnowInitialize ( 
IN PVOID Context 
di 
NTSTATUS 
CDRead( //) 
ULONG LogAddr, 
USHORT LogBlkRead, 
PUCHAR userBuffer, 
PSPECIFIC_DEVICE_EXTENSION dExt 
); 
ULONG 
DriverEntry ( 
IN PVOID DriverObject, 
IN PVOID Argument2 
ys 
ULONG 
CDnowFindAdapter ( 
IN PVOID 
IN PVOID 


Context, 
AdaptersFound, 

IN PVOID BusInformation, 

IN PCHAR ArgumentString, 

IN OUT PPORT_CONFIGURATION_INFORMATION ConfigInfo, 

OUT PBOOLEAN Again 

ye 
BOOLEAN 
CDnowStartIo( 

IN PVOID Context, 

IN PSCSI_REQUEST_BLOCK Srb 

i 
BOOLEAN 
CDnowInterrupt ( 

IN PVOID Context 

ys 
BOOLEAN 
CDnowResetBus ( 

IN PVOID Context, 

IN ULONG PathId 

ys 
DEGRA GAGGIA IGG GIG GIG RRR i kok :k 
Handles interrupts for CDnow. Necessary for March Beta of Windows NT; left 
in for compatibility. Arguments: Context - Device adapter context pointer. 
Return Value: FALSE indicates that this interrupt was NOT from us. 
BEGG GG CIC CIC GGG Or a ior ra a RRR i kok k / 
BOOLEAN 
CDnowInterrupt ( 

IN PVOID Context 

) 


PSPECIFIC_DEVICE_EXTENSION deviceExtension = Context; 
return FALSE; 
} // end CDnowInterrupt () 
/***** Reset Bus from the SCSI Port driver. We basically do nothing here. ****/ 
BOOLEAN 
CDnowResetBus ( 
IN PVOID Context, 
IN ULONG PathId 
) 


PSPECIFIC_DEVICE_EXTENSION deviceExtension = Context; 
return TRUE; 
} // end CDnowResetBus () 
DEGRA CROCCO IGG CAG IGA CGR IAG CI GIR sk ok kak 4k 
Simulate response the SCSI INQUIRY op-code. We make the port driver 
believe that a SCSI CD-ROM is connected. 
ASG GGG CRI GIAGICC GGG GG GAA IO I a a kak a a kak aK ak kaka kok / 
void 
Cdrom_Inquiry (PSPECIFIC_LU_EXTENSION luExtension) 
{ 
INQUIRYDATA *cdromInquiry; 
cdromInquiry = (INQUIRYDATA *) luExtension->SavedDataPointer; 
cdromInquiry->DeviceType = READ_ONLY_DIRECT_ACCESS_DEVICE; 
cdromInquiry->DeviceTypeQualifier = DEVICE_CONNECTED; 
memcpy (cdromInquiry->VendorId, "MedSyn", 8); 
memcpy (cdromInquiry->ProductId, "Cd-Rom Now", 11); 
} 


DOCG OO IOC OGG aI a i ai agi aia aC aa Kk ak ik ak kok 
Simulate a response to the SCSI Read Capacity opcode. We hardcode sector size 
and volume size for compatibility with drives which cannot determine capacity. 
The little endian to big endian conversion was a major gottcha. 

DRAB ROORGGCCRCGG GGG GGG GIG GG IOI I IC a aK i kak kak ak / 
VOID CapacityRead (PSPECIFIC_LU_EXTENSION luExtension) 

{ 

READ_CAPACITY_DATA *capacityRead; 

ULONG FixBlockEnd; 

ULONG FixBlockSize; 

PFOUR_BYTE pEnd = (PFOUR_BYTE) &FixBlockEnd; 

PFOUR_BYTE pSize = (PFOUR_BYTE) &FixBlockSize; 

// Convert to big Endian 

capacityRead = (READ_CAPACITY_DATA *) luExtension->SavedDataPointer; 
FixBlockEnd = 278000; 

FixBlockSize = 2048; 
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((PFOUR_BYTE) & (capacityRead->LogicalBlockAddress) ) ->Byte3= 
pEnd->Byte@; 

((PFOUR_BYTE) & (capacityRead->LogicalBlockAddress) ) ->Byte2= 
pEnd->Byte1; 

((PFOUR_BYTE) & (capacityRead->LogicalBlockAddress) ) ->Byte1= 
pEnd->Byte2; 

( (PFOUR_BYTE) & (capacityRead->LogicalBlockAddress) ) ->Byte@= 
pEnd->Byte3; 

((PFOUR_BYTE) & (capacityRead->BytesPerBlock) )->Byte3= 
pSize->Byte@; 

((PFOUR_BYTE) & (capacityRead->BytesPerBlock) )->Byte2= 
pSize->Bytel; 

((PFOUR_BYTE) & (capacityRead->BytesPerBlock) )->Byte2= 
pSize->Byte2; 

((PFOUR_BYTE) & (capacityRead->BytesPerBlock) ) ->Byte@= 
pSize->Byte3; 


GRE RO SSIES a Cac gaa cia aaa a ia aS cr CaCI a ack aa kak aaa 
ReadCDRom: Transform the Logical block address and size into our 
format for access by read routine. 
FEO ICICI ICCC CCC GIGI OI ICSI GIGI IACI I ACI kk 2k 2k / 
NTSTATUS ReadCDRom(PSPECIFIC_DEVICE_EXTENSION deviceExtension, 
PSPECIFIC_LU_EXTENSION luExtension) 
{ 
struct MYCDB { 

UCHAR OperationCode; 

UCHAR RelativeAddress : 1; 

UCHAR Reservedl : 2; 

UCHAR ForceUnitAccess : 1; 

UCHAR DisablePageOut : 1; 

UCHAR LogicalUnitNumber : 3; 

UCHAR LogicalBlockByte@; 

UCHAR LogicalBlockBytel; 

UCHAR LogicalBlockByte2; 

UCHAR LogicalBlockByte3; 

UCHAR Reserved2; 

UCHAR TransferBlocksMsb; 

UCHAR TransferBlocksLsb; 

UCHAR Control; 

} *cedb; 
ULONG logicalBlockAddress; 
USHORT transferBlocks; 
edb =(struct MYCDB *) luExtension->ActiveLuRequest->Cdb; 
((PFOUR_BYTE) &logicalBlockAddress)->Byte3= cdb->LogicalBlockByte@; 
((PFOUR_BYTE) &logicalBlockAddress)->Byte2= cdb->LogicalBlockBytel1; 
((PFOUR_BYTE) &logicalBlockAddress)->Byte1= cdb->LogicalBlockByte?2; 
((PFOUR_BYTE) &logicalBlockAddress)->Byte@= cdb->LogicalBlockByte3; 
((PFOUR_BYTE) &transferBlocks) ->Bytel= cdb->TransferBlocksMsb; 
((PFOUR_BYTE) &transferBlocks) ->Byte@= cdb->TransferBlocksLsb; 
return( CDRead(logicalBlockAddress, transferBlocks, 

luExtension->ActiveLuRequest->DataBuffer, deviceExtension) ); 

} 
DOERR GAO GOGO CIE GCG ACCC GCC OCIS OCG RC sk xk ik 
Called from SCSI port driver synchronized with kernel with a request 
to be executed. 
FASC CIGCGECCIG IC CIOCIO ICSI IGG SGI GRA RK Kk kak kak kak / 
BOOLEAN 
CDnowStartIo( 

IN PVOID Context, 

IN PSCSI_REQUEST_BLOCK Srb 

) 


PSPECIFIC_DEVICE_EXTENSION deviceExtension = Context; 
PSPECIFIC_LU_EXTENSION luExtension; 
// Determine the logical unit that this request is for. 
deviceExtension->PathId = Srb->PathId; 
luExtension = ScsiPortGetLogicalUnit (deviceExtension, 
deviceExtension->PathId, 
Srb->TargetId, Srb->Lun) ; 
Srb->SrbStatus = SRB_STATUS_PENDING; 
switch (Srb->Function) { 
case SRB_FUNCTION_ABORT_COMMAND: 
Srb->SrbStatus = SRB_STATUS_SUCCESS; 
break; 
case SRB_FUNCTION_RESET_BUS: 
Srb->SrbStatus = SRB_STATUS_SUCCESS; 
break; 
case SRB_FUNCTION_EXECUTE_SCSI: 
if ((Srb->TargetId == 3) && (Srb->Lun == @)) 
{ 


// not at ® or 1 


luExtension->ActiveLuRequest = Srb; 
luExtension->LuState = LS_COMPLETE; 
luExtension->SavedDataPointer = (ULONG) Srb->DataBuffer; 
luExtension->SavedDataLength = Srb->DataTransferLength; 
switch( Srb->Cdb[@] ) 
{ 
// Get CD-ROM Inquiry Data 
case (SCSIOP_INQUIRY) : 
// Setup the context for this target/lun. 
Cdrom_Inquiry (luExtension) ; 
Srb->SrbStatus = SRB_STATUS_SUCCESS; 
break; 
// ReadCapacity: Hardwired data 
case (SCSIOP_READ_CAPACITY) : 
CapacityRead (luExtension) ; 
Srb->SrbStatus = SRB_STATUS_SUCCESS; 
break; 
// Read Cd-ROM 
case (SCSIOP_READ) : 
if NT_SUCCESS (ReadCDRom(deviceExtension, 
luExtension) ) 
Srb->SrbStatus = SRB_STATUS_SUCCESS; 
else 
Srb->SrbStatus = SRB_STATUS_ERROR; 
break; 
case (SCSIOP_TEST_UNIT_READY) : 
Srb->SrbStatus = SRB_STATUS_SUCCESS; 
break; 
// Invalid Scsi Op code 
default: 
Srb->SrbStatus = SRB_STATUS_SUCCESS; 
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break; 
} // of switch 
} // of if 
else 
{ 
Srb->SrbStatus = SRB_STATUS_INVALID_TARGET_ID; 


ScsiPortNotification(RequestComplete, (PVOID) deviceExtension, Srb); 
break; 
// Unexpected Scsi Function Call 
default: 
Srb->SrbStatus = SRB_STATUS_INVALID_REQUEST; 
ScsiPortNotification(RequestComplete, (PVOID) deviceExtension, Srb); 
break; 
} 
// Adapter ready for next request. 
ScesiPortNotification(NextRequest, deviceExtension, NULL); 
return TRUE; 
} // end CDnowStartIo() 
/**xxk findAdapterPort: locate the Io port address of the adaptor *****/ 
USHORT findAdapterPort ( 
PSPECIFIC_DEVICE_EXTENSION deviceExtension, 
IN PVOID Context, 
IN OUT PPORT_CONFIGURATION_INFORMATION ConfigInfo 
) 


t 
ULONG PortBase = BASE_PORT; 
deviceExtension->PortBase = PortBase; 
return LocateAdapterSpecific (deviceExtension, Context, ConfigInfo) ; 
// PortBase; 
} 


Locates the CD controller card, and allocate the I0 ports from NT IO manager. 
Return Value: SP_RETURN_FOUND - if an adapter is found. 

SP_RETURN_NOT_FOUND - if no adapter is found. 
itt EE CC ere er errr rcrrrrrrrrrrrrerterereree rere er eee ee fr tre et Se ee ee 2 eS ag 


ULONG 


CDnowFindAdapter ( 
IN PVOID Context, 
IN PVOID AdaptersFound, 
IN PVOID BusInformation, 
IN PCHAR ArgumentString, 
IN OUT PPORT_CONFIGURATION_INFORMATION ConfigInfo, 
OUT PBOOLEAN Again 
) 
{ 
USHORT portAddress; 
USHORT adaptersFound; 
ULONG returnStatus = SP_RETURN_NOT_FOUND; 


PSPECIFIC_DEVICE_EXTENSION deviceExtension = Context; 
*Again = FALSE; 
returnStatus = SP_RETURN_FOUND; // assum found a valid card 
// If there was no previously configured value for the IRQ, 
// look at the other way to configure the value or use a default. 
ConfigInfo->BusInterruptLevel = 19; 
// £111 in a default a target ID. 
ConfigInfo->NumberOfBuses = 1; 
ConfigInfo->ScatterGather = FALSE; 
ConfigInfo->Master = FALSE; 
portAddress= findAdapterPort (deviceExtension, Context, ConfigInfo) ; 
deviceExtension->PortBase = portAddress; 

if(portAddress == Q) 

{ 


returnStatus = SP_RETURN_NOT_FOUND; 
goto NotFound; 


// Fill in the access array information. 
ConfigInfo->NumberOfAccessRanges = 1; 
(*ConfigInfo->AccessRanges) [0] .RangeStart = 
ScsiPortConvertUlongToPhysicalAddress(portAddress) ; 
(*ConfigInfo->AccessRanges) [0] .RangeLength = 4; 
(*ConfigInfo->AccessRanges) [9] .RangeInMemory = FALSE; 
ConfigInfo->NumberOfBuses = 1; 
adaptersFound = 1; 
*((PULONG) AdaptersFound) == (ULONG) adaptersFound; 
returnStatus = SP_RETURN_FOUND; // assum found a valid card 
NotFound: 
return (returnStatus) ; 
} // end CDnowFindAdapter () 
/****% Driver initialization entry point for system. *****/ 
ULONG 
DriverEntry ( 
IN PVOID DriverObject, 
IN PVOID Argument2 
) 


HW_INITIALIZATION_DATA hwInitializationData; 
ULONG i,status; 
// Zero out the hwInitializationData structure. 
for (i = @; i < sizeof(HW_INITIALIZATION_DATA); i++) { 
* (((PUCHAR) &hwInitializationData + i)) = 9; 
} 
hwInitializationData.HwInitializationDataSize = 

sizeof (HW_INITIALIZATION_DATA) ; 
// Set entry points. 
hwInitializationData.HwInitialize = CDnowInitialize; 
hwiInitializationData.HwStartIo = CDnowStartIo; 
hwInitializationData.HwInterrupt = CDnowInterrupt; 
hwInitializationData.HwFindAdapter = CDnowFindAdapter; 
hwInitializationData.HwResetBus = CDnowResetBus; 
// features not supported 
hwInitializationData.HwDmaStarted = NULL; 
hwInitializationData.HwAdapterState = NULL; 
hwInitializationData.NeedPhysicalAddresses = FALSE; 
// Specify size of extensions. 
// Indicate need buffer mapping but not physical addresses. 
hwInitializationData.MapBuffers = TRUE; 
hwInitializationData.NeedPhysicalAddresses = FALSE; 
hwInitializationData.NumberOfAccessRanges = 1; 
// Specify size of device extension. 
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hwInitializationData.DeviceExtensionSize = 

sizeof (SPECIFIC_DEVICE_EXTENSION) ; 
// Specify size of logical unit extension. 
hwInitializationData.SpecificLuExtensionSize = 

sizeof (SPECIFIC_LU_EXTENSION) ; 
// Fourth parameter below (i) will appear as AdaptersFound parameter 
// when FindAdapter() is called. First try to configure for Isa bus. 
hwInitializationData.AdapterInterfaceType = Isa; 
i = @; 
status = ScsiPortInitialize(DriverObject, Argument2, 
ShwInitializationData, &(i)); 

return status; 


Inititialize adapter. Dummied out this function for compatibility purposes. 
Arguments: Context - Adapter object device extension. 
BECCA GAGS IG GIG ICRC ICICI GCI CGI CCCI RI ACI I ACR a Rk ak ak a8 ak ak ok ok a / 
BOOLEAN 
CDnowInitialize( 

IN PVOID Context 

) 


PSPECIFIC_DEVICE_EXTENSION deviceExtension = Context; 
return TRUE; 
} // end CDnow<Initialize() 


End Listing 





VERSION 2.0 NOW SHIPPING 


The Complete 
C Communications Toolkit! 


Programmers call MagnaeComm C “the com- 
plete C communications toolkit” because it 
supports nearly every product and program 


with hundreds of powerful communications 
features. MagnaeComm C is the fast and easy 
way to add complete communications to all 
your applications. 
























Complete... Serial and fax communications. 

Complete... Support for DOS and MS-Windows in a single package 
(Magna*Comm C for Windows). Use the same function calls in 
both environments. 

Complete... With a terminal program application (similar to MS-Windows 
terminal) to show how to use Magna*eComm C under Windows 
or to add to or modify in your applications. 

Complete... Support for nearly every program or product including MSC 
5.0+/Quick C, Borland Turbo 2.0+, Watcom C and more. 

Complete... Support for the CompuServe B File Transfer Protocol Suite. 

Complete... Network modem support. 

Complete... Diagnostics to determine if devices can share interrupts. 


Plus, complete modem support, chip support, serial port support, flow control, 
terminal emulations, speeds up to 115,000 bps, and an extensive 600 page manual 
with 125 pages of background and 35 example programs. 


ONLY $229 (US) MAGNA*COMM C FOR DOS (PLUS SHIPPING) 
MagnaeComm C for Extended DOS -$299 (US) 

MagnaeComm C for MS-Windows - $299 (US) COMPLETE... 
MagnaeComm C Professional Combo - $499 (US) | SOURCE CODE INCLUDED. 





PLUS FULL-TIME TECH 
SUPPORT. 


For ordering and information call toll free 


1-800-755-7344 5.0 


Major credit cards accepted  °#"2%/ 










Distributed by: SofDesign International, Inc. INTER 
1303 Columbia Dr., Suite 209 Richardson, TX 75081 USA 
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Do you want more support 

in your day-to-day use of OS/2? 
Is your company struggling to 
integrate OS/2 into its enterprise 
computing strategy? Do you want 
to take OS/2 to a higher level? 


OS/2 WORLD 
WILL POINT YOU IN THE 
RIGHT DIRECTION 


The independent technical program, 
featuring over 100 lectures, workshops 
and tutorials, will present you with the 
objective truth — both good and bad — 
about OS/2, IBM, and third-party 
providers. You can count on the infor- 
mation because our top-notch faculty 
won't have a hidden agenda. More 
importantly, the technical program is 
geared to you, the OS/2 customer, not 
the industry. 

The technical program is broken out 
into 8 dynamic tracks: 

e Enterprise-Wide Networking 
¢ Client/Server and Information 

Management 
¢ Local Area Networking 
¢ Power Computing 
e Systems Administration 
¢ Corporate Software Development 
e Personal Programming 


e Multimedia 


AN OBJECTIVE AND 
BALANGED FACULTY 


Classes will be taught almost exclu- 
sively by independent expert users, con- 
sultants, and trainers offering objective 
and balanced information to users and 
managers charged with deploying and 
maintaining OS/2 systems in corporate 
environments. Instructors will be 
experts who work with OS/2 in the field, 
and have implemented OS/2 solutions 


for their companies or clients. 





INDUSTRY-WIDE 
SPONSORSHIP 
GUARANTEES A TOP 
QUALITY EVENT 


Produced by Miller Freeman, Inc., 
the third largest trade show producer 
in North America, the OS/2 World 
Conference & Exhibition is presented in 
cooperation with the IBM Corporation 
and sponsored by OS/2 Magazine, 
OS/2 Developer, DBMS, Database 
Programming and Design, LAN 
Magazine, STACKS: The Network 
Journal, Software Development and 
Dr. Dobb’s Journal. 





CHOOSING THE 
RIGHT NEW PRODUCTS 
CAN BE QUITE A 
BALANCING ACT 


The OS/2 World Products Exhibition 
is the only place you can get a hands-on 
look at the hardware and software that 
can make your system scream. You can 


pose your toughest questions as you 


meet face-to-face with the major players 
in the industry. This world-class 
exhibition will feature leading suppliers 
showcasing applications software, com- 
munications hardware and software, 
databases, network solutions, utilities, 
multimedia tools, and more. The 
exhibition will run Tuesday, Wednesday 
and Thursday so you will have plenty of 


time to get the answers you need. 


SEE THE FUTURE OF 
OS/2 TODAY 


Running parallel to the technical 
program will be dozens of presentations 
by key visionaries at IBM and major 
hardware and software providers. 
Topics include: OS/2 and Workplace 
OS, What It All Means To You ¢ 
Customizing the Workplace Shell with 
REXX ¢ Exploiting OS/2 Software 
Motion Video ¢ Introduction To The 
OSE Distributed Computing 
Environment ¢ And More. 

Don’t miss this opportunity to learn 
what applications and opportunities 
await OS/2 users of the future, and how 
you can stay on the cutting edge. 

Phone, FAX ormail = =... $3 es 
today for more infor- rm os 
mation on the OS/2 7 
World Conference 
& Exhibition. 
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SOME APPLICATIONS NEED A 
REAL REALTIME OPERATING SYSTEM 





Whether you're monitoring a nuclear reactor or handling credit- 
card transactions, you need realtime performance you can count 
on around the clock. The kind of performance QNX° has 
delivered for well over a decade. ~~QNX sustains a host of 
successful mission-critical applications in a wide range of 
industries. From POS to medical instrumentation, from SCADA 
to voice mail, thousands of VARs and OEMs 
rely on QNX for their realtime solutions. It’s 
easy to see why. QNX is a microkernel OS 
combining realtime executive-class speed with 
a rich, self-hosted development environment. 


You won't have to waste time on cross- 
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QNX SOFTWARE SYSTEMS LTD. 





WE WORK IN REAL TIME." 


1-800-363-9001 


(EXT. 104) 
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development, so you'll see faster time-to-market and easier 
maintenance for your applications. ~QNX is remarkably 
flexible. You can easily strip it down to an embedded system or 
build it up to a vast network serving hundreds of CPUs. ~QNX 
follows Open Systems standards like POSIX and TCP/IP, so all 
your applications become all the more portable and 
interoperable. And you can run most popular 
DOS packages - even Microsoft® Windows™ 3.1 
in standard mode under QNX.~So if you're 
looking for a time-tested foundation for your 
mission-critical applications, it’s time for a real 

realtime solution. ~It’s time for QNX. 


TEL:613-591-0931 ¢ FAx:613-591-3579 


© QNX Software Systems Ltd. 1993 QNX is a registered trademark of QNX Software Systems Ltd. Microsoft is a registered trademark and Windows is a trademark of Microsoft Corporation. 


Developing for 
Newton 


Michael Swaine 


ast year, Apple introduced the New- 

ton MessagePad, the first of its per- 

sonal digital assistants, and with it a 

new user-interface model, a new 
development platform, and a new object- 
oriented language, NewtonScript. What 
follows is a look at what Newton real- 
ly is (and isn’t), a view of the first New- 
ton Platform Development Conference, 
a peek at Newton development using 
the Newton Toolkit (NTK), and some 
observations on the unique challenges 
Or Opportunities in building and selling 
software for Newton. 


What is Newton? 

That’s the question Apple was asking 
in its pre-Christmas commercials. Apple’s 
answer, predictably, was that Newton is 
what the world needs now: love and 
understanding, peace and productivity. 

After buying a Newton MessagePad 
and accessories; reading numerous mag- 
azine articles, online chats, advertisements, 
press releases from both Apple and third- 
party vendors, and technical docs from 
Apple’s PIE division; attending the first 
Newton Platform Development Confer- 
ence; working through the sample code 
in the beta Newton Toolkit CNTK); and 
playing around at writing simple New- 
ton apps, I’ve come to the conclusion that 
the real issue is what Newton is not. 

Newton isn’t simply a handheld 
personal digital assistant manufactured 
by Sharp and sold under Apple and 
Sharp logos. The Apple Newton Mes- 
sagePad (or Sharp ExpertPad, which is 
essentially the same device) is only the 
first product based on Newton Techno- 
logy. Others will be announced this year. 

Newton isn’t one form factor. Future 
Newtonian devices can be expected to 
look like anything from telephones to 
clipboards to blackboards. 

Sorry, I shouldn't have said, “look like 
telephones.” I should have said, “be tele- 
phones.” At that point, these devices 
will start to be actual consumer prod- 
ucts, which Newton isn’t today, despite 
the charter of Apple’s PIE division (to 
which Newton belongs). 

Newton isn’t just a line of Apple 
products. Apple is licensing the New- 
ton software technology to other ven- 
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dors, who will build their own devices 
and sell them under their own labels. 
Thus, the future of Newton is not sole- 
ly in Apple’s hands. 

Newton isn’t dependent on a single 
processor. Although current devices use 
the ARM610 RISC chip, the applications 
written for Newton compile to a byte- 
code representation, completely pro- 
cessor independent. No doubt, the New- 
ton software itself will be implemented 
on other processors. My guess is that 
the PowerPC chip will be an early port. 
(Yes, Newton pays for processor inde- 
pendence in speed— more about this 
shortly.) 

Newton is an operating system. Mac- 
Week columnist Don Crabb has even sug- 
gested replacing the current Macintosh 
Finder with something more Newtonian. 
But it isn’t a computer operating system. 
Newton devices aren’t computers and 
aren't designed to do things that com- 
puters do. The concept behind Newton, 
apparently, was something like this: Who 
hasn't said, “I can handle the big things; 
it’s the nagging little things that hang me 
up.”? Newton is for the little things. 

While I’m saying what Newton isn’t, 
I will also address some of the initial 
(mis?)perceptions of the MessagePad. 


Perception: The handwriting recogni- 
tion is inadequate. 

Reality: The MessagePad suffered for 
not being what editors and writers want- 
ed it to be, taking some really excessive 
abuse for the perceived deficiencies in 
its handwriting recognition. But it’s not 
supposed to be a substitute for a re- 
porter’s notebook. In a more appropri- 
ate use, say as a tool for a field-service 
technician, handwriting recognition is 
less important. That said, I agree that 
MessagePad’s handwriting recognition 
is inadequate. But that doesn’t make the 
device unusable. 

Perception: Some pieces are missing: 
If this is a communication device, 
where’s the communication? 

Reality: Dead on. But since release, New- 
ton has collected some communication 
aids. The Connection Kit lets you move 
files to and from a Mac or a Windows ma- 
chine (there are two versions) and sup- 





ports some file synchronization. There’s 
a 9600-baud fax modem the size of a 
cigarette pack, a modem on a PCMCIA 
card, a pager on a card (plug the card in 
and the page messages become text you 
can save or edit), Apple’s NewtonMail 
electronic-mail service with links to most 
other services, a third-party service that 
bridges from an e-mail service to a pag- 
ing service so you can get e-mail via the 
pager card, and some other things. These 
all cost extra, of course. A future version 
of the MessagePad may have more com- 
munication capabilities built in. 
Perception: At $700, it costs too much. 
Reality: By the time you’ve added the 
necessary connection kit, fax modem, 
RAM card, and battery pack, it'll cost 
you a lot more than $700. 


Universal Attraction 

In December, MessagePad in hand, I at- 
tended the first Newton Platform De- 
velopment Conference. Usually I cover 
these conferences as press, but this time 
I was there as a developer. 

Nonetheless, my journalistic antennae 
were up, scoping out the crowd. As 
soon as I arrive at one of these events, 
I ask myself, who are these people? In 
this case, I got the impression of a mot- 
ley group. There were surely more 
women than at any developer confer- 
ence I’ve attended. And more nontech- 
nical or at least less-technical people. 
There were more people who did not 
identify themselves as developers. A man 
with whom I ate lunch seemed typical: 
He had hit upon a vertical-market niche 
about which he knew a thing or two, 
he said, and was planning to sell New- 
ton MessagePads, with his software in- 
stalled, directly into this market. 

That was one type of attendee, the 
vertical expert. There were also a lot of 
professional developers and quite a few 
marginal hackers (ike me, doing my bit 
to pull down the curve). But on average, 
this seemed to be not quite the techni- 
cal audience you’d see at OOPSLA. 

Another attendee told me afterward that 
he had talked to several Windows devel- 
opers at the show. Were they concerned 
that Apple hadn't released the Windows 
version of the NTK yet? No, they were 
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willing to buy a Mac to program on. Al- 
though not interested in developing /or 
the Mac, they had no objection to devel- 
oping on the Mac. At the very least the 
story shows that Newton is being per- 
ceived correctly as a new platform, hav- 
ing nothing to do with the Macintosh. 

The conference was organized along 
three tracks: International Newton Mar- 
ketplace (marketing), Orientation to 
Newton Development (summaries of 
chapters in the NTK manual), and Ad- 
vanced Newton Development (the good 
stuff). I skipped back and forth between 
sessions in the last two tracks and 
picked other people’s brains during 
breaks to get the goods on the market- 
ing sessions. 


I’ve Hit the Wall, Wally! 

I attended sessions on NewtonScript and 
the Newton object model (soups and 
stores are the key words there) and view 
systems; prototypes and communica- 
tions; and a session on intelligent assis- 
tance, or IA. 

IA is a technology that you can im- 
plement in your apps that allows the 
user to select some text (or sometimes 
let IA guess what text should be se- 
lected), tap the Assist button, and have 
the text interpreted as a command, 
which IA will then attempt to execute. 
Commands that JA already understands 
include things like: 


e Remember trim hedge (adds “trim 
hedges” to your to-do list). 

e Call Mom at work (finds any name en- 
tries that include “Mom” as part of their 
data, offers you the list if more than 
one matches, retrieves the work phone 
number for the selected Mom, checks 
to see if area code or dialing prefix is 
necessary, and offers to dial Mom). 

e Lunch with Jake Tue (schedules a 
12:00 appointment with Jake for next 
Tuesday). 

e Fax this to Larry (prepares a fax cov- 
er sheet and offers to fax the current 
document to Larry, using his fax num- 
ber, of course). 

e Birthday Mike 12/10 (creates an an- 
nual reminder of Mike’s birthday on 
December 10). 


Players of adventure games will rec- 
ognize the syntax. You can add vocab- 
ulary that your application knows about 
and have IA pass commands along to 
it. But there are some tricky issues in 
this. The user doesn’t have to be in your 
app to use its vocabulary. Suppose two 
games both implement the verb “play.” 
IA could get confused if they don’t do 
it right; and, frankly, IA can get con- 
fused in any case. 

Nevertheless, I think IA is an interest- 
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ing interface element. Consider: The user 
may invoke your app via some verb like 
“pay” without ever clicking on an icon 
or really thinking about the fact that your 
application is what’s doing the job. Ap- 
plications that use IA effectively can feel 
like disembodied capabilities. Intriguing. 
On the last day of the conference, 
there was a special, unannounced ses- 
sion typical of Apple conferences. It was 
announced early on the first day— typ- 
ical for unannounced Apple events. 
Speculation was rife that this would be 
a sneak peek at the clipboard-format 
Newton. Nope. It was, atypically, some- 
thing with more substance than flash. 


The problem: Compiling to byte code 
for portability incurs a cost in execution 
speed. Newton apps that I have seen 
tend not to be horribly handicapped by 
this, but even the bundled apps can be 
annoyingly slow, and it’s not hard to 
imagine apps that will drag the machine 
to a grinding halt. 

The solution: The Father of Newton- 
Script, Walter Smith, is working on an 
enhancement to the Toolkit that will al- 
low native-mode compilation and opti- 
mization for specific hardware, on a 
function-by- function basis. He showed 
some examples. A QuickSort routine, 
written in NewtonScript, was speeded 
up by a factor of 40 by taking it native. 
A compute-and-draw routine from.an 
early version of the Maze game Claris 
is distributing was speeded up by a fac- 
tor of seven. 


This isn’t going to be of any use for 
Toolbox calls, but for compute-intensive 
code, it ought to be very nice. 

Here’s how it will work when New- 
ton is ported to other processors: You 
write one app, but flag the functions 
that you want to have run native. You 
deliver it on various platforms. On those 
platforms that have implemented native- 
code optimization, this will be applied 
to your routine; on others, you'll just get 
the usual byte code. 

Right. In neither case do you get to 
program in the native language of the 
target processor and do your own op- 
timizing. That’s the price of portability. 


Lifting the Toolkit Lid 
As I run through some of the compo- 
nents and capabilities of the NTK de- 
velopment system, please understand 
that this is not a review. NTK is not, as 
I write this, a released product. Some 
chapters in the doc are yet to be writ- 
ten in the version that I have, and much 
of the sample code is “unblessed” (Cin 
other words, back up your system be- 
fore you download it). 

NTK consists, primarily, of the NTK 


application, something called Book- 
Maker, scores of pieces of sample code, 
and what’s shaping up to be pretty de- 
cent printed documentation. 

NTK itself looks a little like Syman- 
tec’s Think environment, but has a fla- 
vor all its own. 

As with Think, your application in 
progress is called a “project.” Its com- 
ponents can be viewed and accessed via 
a Project window; there’s also a Layout 
window, any number of Browser win- 
dows that you create, and an Inspector 
window, where you can enter Newton- 
Script code, execute it remotely on a 
connected Newton, and get back results. 

The Layout window is a visual rep- 
resentation of the Newton screen; al- 
though it is not an emulator, it does have 
a preview mode that shows how objects 
will appear on the screen. There’s also 
a palette of object prototypes (not the 
right terminology) that can be dragged 
onto the Layout. 

There’s an additional file named Mes- 
sagePad, which you drag into a folder 
named Platforms. When there are oth- 
er platforms, you will be able to drag a 
different platform file into the folder, 
and the Layout window will reflect its 
form factor. 


Making Book on Newton 

NTK will let a lot of people develop ap- 
plications who would not be able to do 
so for the Mac or for Windows. Simple 
applications can be put together via vi- 
sual programming methods, using sup- 
plied components. 

The protoApp template is one such 
component. In NTK, you can select the 
protoApp template from a long list of 
templates or click on its icon in a palette, 
then drag out a rectangle in the Layout 
window. This gives you a standard ap- 
plication with frame, title, and go-away 
box. Standard buttons and text-entry 
windows can be dragged into the ap- 
plication window just as easily. 

These visual elements are called 
“views.” They are the visual representa- 
tion of objects whose properties reside 
partly in RAM, partly in ROM, dragging 
one of them inside another establishes 
an inheritance relationship between 
them. But the beginning developer 
doesn’t need to know all this. Nor does 
he or she need to know that building 
from templates draws on a different, in- 
dependent inheritance scheme, or how 
these inheritance schemes interrelate. 
The beginning developer can just drag 
the pieces into place— adding text to 
titles, picking properties from lists — and 
build the app without writing any code. 

As a result, some simple Newton apps 
have appeared very quickly. Some of 
these are highly content oriented. NTK 
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(continued from page 116) 

includes the BookMaker application (not 
supplied with the first betas) which is 
particularly accessible to nonprogram- 
ming developers, like those people I 
saw at the conference. 

BookMaker is an aid to creating elec- 
tronic books that are to be delivered on 
Newton platforms. Is this a good format 
for reading books? I consider it part of 
my job to take such questions seriously, 
so I actually read, on a Newton Mes- 
sagePad, Joseph Conrad’s Heart of Dark- 
ness, Which someone has poured into 
an electronic book. My conclusion: Few- 
er typos would have made this homage 
to Conrad more convincing, but it was 


For ease and 
convenience, 
these and other 
VNR books may 
now be ordered 
toll-free by calling 
1-800-544-0550 
(Dept. Z 1586) 
Or GO VNR on 
the CompuServe® 
Network. 


Van Nostrand Reinhold 
115 Fifth Avenue New York, NY 10003 
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easy enough to read, way more conve- 
nient than a PowerBook. (And yes, I 
have done the dirty work to support 
that comparison: Last summer, I read 
Jurassic Park on a PowerBook, so you 
don't have to.) 

But the kinds of books that really 
make sense on this platform are refer- 
ence books for communications and 
travel, and job-related manuals for sales 
and field-service people. A book of 800 
numbers, for example. You can already 
find some good examples of such books 
on various online services. 

With BookMaker, you mark up a 
word-processing document with a spe- 
cial markup language (simple dot com- 


VNR KNOWS 
SOFTWARE 
ENGINEERING 
Why do breakthroughs on one 


software project not yield similiar 
results on another? Why does soft- 
ware obey its own undisclosed laws? 
Finally these questions are answered 
in a book which gives you the tools 
to anticipate, avoid and correct 
defects when engineering software. 
SYSTEMS, SOFTWARE AND 
QUALITY ENGINEERING by 
Arthur E. Ferdinand ($59.95 
0-442-01730-8) 


FOR A LIST OF THE 


BEST NEW BOOKS IN 
SOFTWARE TESTING 


Whenever you develop software, 


it is essential that it is documented 
and reproducible at every stage of 
its development. CONFIGURATION 
MANAGEMENT FOR SOFTWARE 
by Stephen B. Compton and Guy 
Connor ($39.95 0-442-01746-4 ) 
offers clear and simple procedures 
for documenting everything you 

do, every step of the way. It may 

not sound important until you 


experience the alternative. 


Call VNR at 
1-800-544-0550 
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mands, like .Title Heart of Darkness and 
.Author Joseph Conrad), then run it 
through BookMaker. You get a Newton 
package, which you can augment using 
NTK. Every element is scriptable with 
the full power of NewtonScript. You can 
add any degree of power to the book 
you create through this method, in- 
cluding adding IA. But the markup lan- 
guage itself has a lot of capabilities, such 
as automatic index and table of contents 
generation, mixed font specification, in- 
clusion of PICTs and bitmaps, and book- 
marks and other navigational aids. 

Of course, BookMaker also has limi- 
tations. You have to work around the 
file-size limitation of Claris XTND tech- 
nology, on which BookMaker relies for 
reading files. And you are currently lim- 
ited to the Geneva and New York fonts, 
which are in the Newton ROM. In the 
future, you'll be able to download fonts. 

That’s the low end of Newton devel- 
Opment. You can develop real commer- 
cial apps without much effort and with 
zero to very littlke programming. That 
model won't work for most interesting 
apps, though. These will require that 
you get seriously into NewtonScript, an 
interesting language. We'll do just that 
in a future column. You can put a sig- 
nificant amount of effort into a Newton 
app, particularly if you get into com- 
munications and device control. But 
nowhere does Newton development ap- 
proach the complexities of Windows or 
Mac development. 


Channel Surfing 
It was encouraging to hear Michael Spin- 
dler speak, as he did at the conference, 
about the need for a new approach to 
software- distribution channels. He spoke 
of the need to open things up for the 
small developer and made it sound like 
that was a priority for Apple. I hope it 
is, and that he wasn’t just giving a sales 
pitch for Apple’s new online service. This 
Newton software market is not, or had 
better not be, a shelf-space battleground. 
There seem to be indications that Ap- 
ple is serious about small developers in 
the Newton software market. Of the var- 
ious distribution methods discussed at the 
conference (PCMCIA cards, NewtonMail, 
Apple’s StarCore and PIE Partners pro- 
grams, online services, Mac or PC disks), 
StarCore sounds particularly interesting. 
It's a comarketing program, but the Star- 
Core folks seem willing to entertain quite 
a variety of different plans, tailored to the 
particular needs of the developer. I heard 
some really small developers who had 
made their pitch to StarCore and had not 
received a definite No. 


DDJ 
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Scores more touchdowns for your communications 
development in C and C++ for Windows, DOS, and OS/2 


Comm-++ 2.0 


C++ class library for Windows 3.1™, MS-DOS®, and OS/2. 
Device independence through inheritance. 47 big classes. 


Supports Microsoft C/C++, Visual C++, Borland C++ and 
other popular compilers. 

COM1..COMS8, standard, and intelligent multiport boards. 
Baud rates to 115,200; drives 8250, 16450, and 16550 type 
UARTs including FIFO trigger level controls. 

XON/XOFF, RTS/CTS, and DSR/DTR handshaking. 


XMODEM, YMODEM, ZMODEM, Kermit, and ASCII file | 


transfer protocols; 1K, G variants, RLE data compression, 
ZMODEM crash recovery, subdirectory recursion, more. 


VT52, VT100, ANSI & TTY terminal emulation classes. 
Modem control class includes handy WaitForOK () . 


Screen drivers include TextWindows™, DataWindows, and 
compiler independent "Vid" function set. 


ViewComm 3.0 


Full featured RS-232 "Datascope" with graphic breakout | 


box for PC or laptop. Uses 1 or 2 serial ports. 


Monitor, capture data in ASCII, EBCDIC, Baudot to 115,200 - 


baud. Supports 8250, 16450, and 16550 UARIs. 
Capture to buffer or file, review, string search. 


Unlimited triggers on modem status, data patterns, 
including wildcards! 


View data in hex, octal, decimal, binary, with graphic 
control codes. Special fonts provided for EGA and VGA. 


Variable resolution timestamps for each character, down to — 


1 msec. optionally stored with data. 

Source mode lets you send from file, keyboard or both. 
Users say it easily pays for itself the first time you use it! 
Cables, setup guide, and reference manual included. 





rey Call Greenleaf Software today for complete information 


or to order. Major credit cards, COD, approved purchase 
orders. Same day shipment in most cases. 


(800)523-9830 ortae| 


(214)248-2561 FAX: (214)248-7830 
BBS: (214)250-3778 for free demos and information. 
16479 Dallas Parkway, Suite 570, Dallas, TX 75248 
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NEW! CommLib’ 5.0 


Enhanced support for MS Windows includes language 
independent DLL and message notification for commun- 
ication events (WM_COMMNOTIFPFY). 

Level 2 device independent functions for these drivers: 
MS Win32, MS Windows, Greenleaf Standard, Fast, Smart 
DigiBoard™, Smart Arnet™, Smart Star Gate™, Sparkle™, 
BIOS, Extended BIOS, Polled mode, MODEM Assist Plus™, 
and FOSSIL. 

286 and 386 Protected Mode for Phar Lap and Rational 
Systems DOS extenders. 

CompuServe B+, XMODEM, YMODEM, ZMODEM (with 
crash recovery), Kermit, ASCII file transfer protocols. 


Unlimited number of ports for ISA, EISA, and MCA. 


Modem controls, keyboard, screen, RTS/CTS, DSR/DTR & 
variable level XON/XOFF handshaking, and much more. 


Exclusive: Mix different multiport boards in a PC! 


~PowerComm” 1.1 


Y PowerComm Toolkit 1.1 for Windows 3.1 provides — 


CommLib DLL and VxD. (Requires CommLib 5.0) 


Y/Y Drives most standard multiport boards; share board 


among multiple Windows 3.1 and/or DOS apps. 


Y Throughput multiplier—much faster than Windows or 


other driver. The VxD is written using CommLib's fast 
assembler code in 32-bit flat model. 





a FREE Source code--all of it! 

ao FREE Unlimited Tech Support. 

a FREE online help system. 

a FREE access to Greenleaf BBS. 

o Professional ele same day 
shipment, personalized service. 


GREENIEAF °Ssmuiickourn 





© 260-day money-back guaranty (if 
source code not opened). 
a Other C and C++ programming 


tools available. 


Greenleaf CommLib 5.0 NEW! $359 
Greenleaf CommLib Professional $538 
Greenleaf PowerComm 1.1 $179 
Greenleaf Comm++ 2.0 $249 
Greenleaf ViewComm 3.0 $399 


Real-Time Graphics and User Interface Tools 


Design and implement a complete instrument interface for DOS using Rev. 4.0 


Cle Real-Time Window Control - Windows 
cre can be moved, resized, overlapped, hidden, 
iconized and closed using the mouse. 


Actual Frequency _ zx — Real-Time Display Graphics - Scrolling 
graphs, Sweep graphs, Bar graphs, Meters, 
Clocks, Panel meters, Annunciators and 
7-Segment displays. 


= os = , i i si ai 
ne ‘eee 


Control Objects - Push buttons, Multi-pole 
switches, Knobs and Scroll bars. 


Menus - Pull-down graphics mode menu 
system with help and hotkey support. 


Dialog Boxes - File list, General input, 
Check-off box, General list, Text output and 
Message dialog boxes. Multiple dialog box 
types can be combined together into a single 
form. 





The objects of a virtual instrument panel can be "locked" together and 
then opened, closed, moved and resized as a single instrument. 


High Resolution Printer Support - 
Hardcopy output for HP LaserJet, HP 
DeskJet (including color), HP PaintJet, HP 
Plotter, Epson 9-pin, Epson 24-pin, and 
Postscript printers. 


Misc. Features - Real-Time data reduction, 
non-preemptive real-time scheduler, real- 
time digital filtering, PID control, and high 
speed FFTs. 


Compiler Support - Turbo/Borland C++ 3.1 
and 4.0, Turbo/Borland Pascal 6.0 and 7.0, 
Microsoft C/C++ 7.0 and Visual C++, and 
Watcom C/C++ ¥ 9.5. These tools are for 
use in DOS application programs, not MS 
Windows programs. 


Data Acquisition Support - These software 
tools do not contain data acquisition 
drivers. The tools are designed to be used 
with any driver which can read and convert 
data into a floating point format using one 
of the supported compilers. 





Combine the FFT routines with real-time graphs and controls to create an 
instrument interface worth thousands of dollars. 


Ordering Information - Price $300. You 
must specify compiler (Borland C++, 


Microsoft C/C++,Watcom C/C++ * or See simulated instruments so 
Borland Pascal) when ordering. Shipping ee ° ° ° 

$8 USA, $12 Canada, $36 most other realistic, you will find yourself reaching 
enna: for the controls! 


QUINN-CuRTIS, INC ¢ 35 HIGHLAND CIRCLE ¢ NEEDHAM MA 02194 USA @ TEL 617/449-6155 ¢ FAX 617/449-6109 
CIRCLE NO. 433 ON READER SERVICE CARD 





C PROGRAMMING 


Templates, Patents, 


Docs, and Phones 


Al Stevens 


ast month I talked about how my 
min and max template functions do 
not work when one argument is 
const and the other is not. The point 
of the diatribe was that sometimes noth- 
ing works as well as reverting to old 
habits, in this case the use of a #define 
macro. The behavior that caused the 
problem is that exhibited by Borland’s 
C++ 3.1. Iran similar tests against Wat- 
com C++ and did not have those prob- 
lems. I cannot tell you which compiler 
is correct, because I do not know what 
the ANSI] C++ standard will say when it 
is published sometime in the next cen- 
tury. Borland’s version 4.0 with its non- 
sensical no-nonsense license is out, but 
I have not yet installed the shipping ver- 
sion. If you have not heard about the 
license, you should know that it attempts 
to restrict the types of applications you 
can write (no operating systems or 
databases, for instance) and requires 
you to obtain a royalty-free license if 
you distribute more than 10,000 copies 
per year of your application. As you 
might expect, this has ignited a firestorm 
amongst programmers worldwide. I'll 
delve into this in depth in next month’s 
column. The beta version has the same 
problem, and compounds it by includ- 
ing its own min and max template func- 
tions with const parameters. Now, the 
usage works only when both arguments 
are const. | had to comment out their 
templates and use my own. 
My min and max templates work very 
well, thank you. I am thinking about 
patenting them. No? Read on. 


Patently Absurd 

Last month’s editorial in DD/ told you 
about the patent Compton’s NewMedia 
received for access to multimedia data- 
bases. Although the Patent Office has 
since decided to review the Compton’s 
patent, the implications of that patent 
and the intentions of its holder are 
enough to shake the foundations of soft- 
ware developers everywhere. Here’s an- 
other one, although in a smaller scope. 
I am concerned about what it implies. 
Not only might D-Flat’s example Memo- 
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pad program be subject to the licenses 
claimed by the holder of this patent, but 
so might the products of every major 
software developer in the country. 

Psytronics of Princeton, New Jersey 
holds patent 4,540,292. I learned about 
it when an associate received a letter 
from a lawyer suggesting that my 
friend’s software product, a contact man- 
ager, might be subject to licensing by 
the patent. 

The patent abstract describes an “elec- 
tronic calendar display in which each 
column always corresponds to a par- 
ticular day of the week....” According 
to the patent, all prior-art patents were 
for devices where the first day of the 
month is always in the upper-left cor- 
ner of the calendar matrix, sliding the 
days of the week around to match the 
current month. Seeing a need for a cal- 
endar display that resembles the real 
thing, the company designed one, built 
it, and patented it in 1985. 

My friend’s contact manager displays 
a calendar on the screen, similar to the 
one in Windows Calendar, Borland’s Side- 
kick, Casio Boss, and every other hard- 
ware and software product that includes 
a calendar, including D-Flat’s Memopad. 
I called John Olivo, the lawyer who sent 
the letter, and asked if he believed that 
the patent covered software- generated, 
screen displays of calendars. He said that 
my question was a complex one but that 
they had no position on that issue at the 
moment. I asked many questions about 
their plans and intentions with respect to 
the enforcement of this patent as it would 
apply to us programmers, and he was 
politely evasive. He would not tell me if 
they sent similar letters to Borland, Mi- 
crosoft, or anyone else. He did, however, 
know about their calendar- displaying 
products. 

Mr. Olivo hastened to assure me that 
the letter was meant as a friendly in- 
quiry to potential licensees and that my 
friend should not be concerned. He 
would not, however, say whether there 
would be any further legal activity with 
respect to companies who chose to ig- 
nore or respond with an equally polite 






















































































“no thanks” to their invitation to license 
the technology. 

Perhaps this one has gone as far as it 
will go. Mr. Olivo told me that Psytronics 
is a small company. I cannot guess 
about their intentions or their resources. 
But the granting of this patent portends 
a much bigger concern for us. The 
patent office is handing out patents for 
so-called inventions that they do not 
understand, and it seems that anybody 
can patent anything if it involves or im- 
plies software. What does that mean to 
us programmers? There we sit at our PC, 
building the next great American appli- 
cation. We use algorithms taken from 
our own experience and research and 
from the libraries and literature of the 
industry. We use them trustingly, never 
knowing which of them is covered by 
a patent or a patent pending filed for 
by a naive “inventor” and granted by an 
incompetent or uninformed bureaucrat. 
The application hits the big time. It 
catches the attention of the dozen or so 
patent holders who sit quietly and watch 
patiently for their opportunity. Like par- 
asites, they line up to feed on our rev- 
enues. Each one expects a license fee, 
a percentage of our gross sales. Get 
caught by enough of them, and the 
leech percentages add up until we are 
out of business. 

My friend asked what he should do. 
I gave him the only counsel that I could 
give, the one piece of advice that sets 
my teeth on edge and sends shivers up 
my spine. I told him to call a lawyer. 


Creative Bookmaking 

The task of writing a D-Flat++ pro- 
erammer’s guide is upon me, and I am 
faced with a common dilemma. How do 
you effectively document a class library? 
Approaching this from the view of the 
user, the programmer who will use the 
classes, I remember problems I’ve had 
reading the class-library documentation 
for OWL, MFC, and others. They de- 
scribe the ciass interface in terms of the 
public member functions that are in the 
class itself, making you search up the 
tree for inherited functions. I sure don’t 
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want a hernia from carrying the docu- 
ment from the shelf to my desk, but I 
need all the information when I need it, 
and therein lies the problem. 

As a class user, a programmer wants 
to know the nature and behavior of the 
class’s public interface. You are not al- 
ways concerned about whether a par- 
ticular member function is inherited, 
overridden, or unique to the class be- 
ing used. There are exceptions, of 
course. If you are dealing with pointers 
or references to a base class, you need 
to understand the differences between 
the behavior of the virtual functions in 
the base and the derived classes. But, 
in most cases, you really just need to 
know how the methods behave in the 
context of the object that you instantiate. 

Reading about the derived class in the 
typical programmer’s guide, you learn 
about its member functions. Then, you 
must look at all of the public member 
functions of all the base classes up the 
tree to see all of the methods available 
to the derived object. Class definitions 
are sometimes presented in alphabetical 
order, and the search involves leafing 
through one or more books, holding 
your fingers, pencil, comb, mouse, cof- 
fee spoon, or whatever is handy between 
the pages to mark your place. Other 
times the classes are grouped in cate- 
gories, and you have to do all of the 
above, plus root through the index and 
hope that it is correct. In either case, you 
have a desk and lap full of books with 
bookmarks sticking out everywhere. 

The documents could save you all that 
book-jumping by repeating the descrip- 
tions of all of the base methods for all of 
the derived classes. Two things would 
happen. First, you would need a front- 
end loader to carry the books around. 
Second, class documentation would get 
out of sync when base classes changed, 
particularly if the project suffers from a 
less than conscientious documentation 
effort. The usual approach is for each 
class to document its own methods, so 
nothing is duplicated. It solves the bulk 
problem but is less convenient for the 
programmer, who must search a com- 
plex class hierarchy to find all the meth- 
ods available to an object. 

These are the problems of paper doc- 
umentation, and it makes me wonder 
why we still deal with paper. Isn’t pa- 
per finally obsolete? All of the manuals 
for Borland, Microsoft, and Symantec 
compiler products now come on CD- 
ROM along with the software itself. They 
use effective presentation and search 
engines to display the documentation 
on the screen. But they also deliver 
books, which contain the same infor- 
mation and have no search engines be- 
yond the traditional tables of contents 
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and indexes. Why do they go to the ex- 
pense of duplicating this information, 
using up trees, weighing down the mail 
person’s sack, and filling our book- 
cases? Part of it is our fault. Program- 
mers gripe if the vendor cuts back on 
documentation, even when the text is 
available electronically and with an in- 
telligent search engine. We perceive the 


A properly designed 
class browser 
would group the 
methods under each 
class that can use 
them, regardless of 
where they come 
from in the class 
hierarchy 





value of a product to be relative to the 
bulk of the package. Marketing strate- 
gists know this. They like it when the 
product is in a big box. Buyers are sub- 
liminally induced to attach greater cred- 
ibility to the bigger package. It gets more 
room on the retailer’s shelf and, there- 
fore, more visibility. There is also the 
belief that products with documentation 
endure less piracy because the users 
want the books. 

Electronic documentation is a better 
idea. It weighs ounces. It is more cur- 
rent. (No more README.DOC files to 
tell us what changed since press time.) 
You can find things by using intelligent 
Boolean queries. Electronic documenta- 
tion can have hypertext links. It can talk, 
play music, and show video clips. It can 
include examples that you can compile 
and run on your computer. You can click 
on an element in a class-hierarchy dia- 
gram and see its interface methods. Click 
a method and see its description. When 
a new version of the compiler or tool 
comes out, your dog can use the old 
CD-ROM as a Frisbee. Save trees, land- 
fills, and cervical vertebrae. 

What is more, a properly designed 
class browser would group the meth- 
ods under each class that can use them, 
regardless of where they come from in 
the class hierarchy. It would use single 
copies of the function descriptions, ap- 
plying them according to the class dec- 
larations taken from the same source- 
code header files that the compiler uses. 


As I ponder the business of writing 
D-Flat++ documentation, I am happy that 
developers of public-domain software 
are not bound by the parameters of a 
market-driven economy. I don’t need to, 
and will not print a manual. At the very 
least, the document will be a text file. 
With time, however, I will build a class 
browser that does what I just described. 

Back to the issue of commercial pro- 
grammer’s tools. Ask yourself this. If the 
Zippo C++ Compiler and Applications 
FrameUp product came in a mailer with 
only a CD-ROM and a booklet that says 
to run SETUP from the Program Man- 
ager, would you still buy it? How about 
at a reduced cost that allows the ven- 
dor to recover development costs and 
still make a profit? What if you could 
buy the bound documentation as an op- 
tion? Or in a bookstore? If you would 
not do any of these things, if you insist 
that every product and every upgrade 
comes with all the manuals printed and 
bound, ask yourself why. 


Where is Don Ameche 

Now That We Really Need Him? 
Looking to the 21st century, we foresee 
an era driven by technology. The White 
House is on the Internet. The informa- 
tion highway leads directly to the pin- 
nacles of power, and anyone can ride. 
Astronauts are walking in space, re- 
placing the Hubble’s 80286 with a 386, 
fixing things so that we can see to the 
edges of the Universe. Up and down 
Silicon Valley, programmers of compil- 
er tools are chiseling out new and in- 
novative ways for me to add sculptured 
radio buttons to my cold-steel, shaded, 
sculptured, three-dimensional dialog 
boxes. These are exciting times. 

I’m living this week in the heart of the 
Valley, having come to spend some time 
in the editorial offices of DD]. This is 
where the guardians of the future of our 
technology live, work, and shape our 
lives. I should be exhilarated just to be 
here where it all happens. At first I was. 

Then I tried to make a telephone call 
from a Best Western motel room in San 
Mateo to a residence in Los Gatos, about 
40 miles to the south. 

The phone in the motel room has an 
insert with printed instructions for us- 
ing a credit card. Dial 9-0, then the area 
code and phone number, it says. I do. 
After several clicks, beeps, rings, and 
other electronic R2D2 sounds, an oper- 
ator comes on the line. How may he 
help me? I want to charge this call to 
my credit card. What number are you 
calling? The one that I dialed. Would 
you tell me what it is? I do, and he asks 
for my credit-card number. 

I should have been suspicious. Back 
East, you don’t have to talk to these peo- 
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(continued from page 122) 

ple. You dial the way you are told, the 
phone goes “boing,” and you dial the 
card number. “Thank you for using 
AT&T,” the synthesized lady says, and 
the call goes through. When you involve 
the real people, the rates go up. No mat- 
ter, I told him my credit-card number. 
Sorry, says he, I can’t bill to that credit 
card. Why not? It’s for a different carrier. 
Yeah, says I, AT&T. We are a private 
carrier, says he, and you will have to 
call an AT&T operator. 

The phone’s instructions say to dial 9- 
000 for AT&T. I do and get an AT&T op- 
erator, a real person again. I repeat the 
drill, and the phone goes dead. J try again 
and tell the new operator what happened. 
She promises to stay with me for the du- 
ration. I repeat the phone number and 
credit card number for the third time. “Sor- 
ry, I can’t place this call.” What? Is my 
card invalid? No, your card is fine, but I 
can’t place the call to that number. Why 
not, is it a local call? No it’s a long-dis- 
tance call, but it’s not long distance 
enough. That, dearhearts, is a direct quote. 
Here I am, says I, with a telephone in 
one hand and an AT&T credit card in the 
other, and you won't put the call through; 
what can I do? Her supervisor comes on 
the line. Now I have a person with au- 
thority. Call a Pacific Bell operator, he 
says, they can bill to your AT&T card. 
How do I get them? Dial 9-0. 

I dial 9-0. The operator answers, and 
I start over again. Sorry, says he, I can’t 
bill to that number. It’s déja vu all over 
again. Are you a Pacific Bell operator? 
No I’m a CTS operator, and we are a 
private carrier. How do I get a Pacific 
Bell operator? Dial 9-0. That’s how I got 
you! May I suggest that you call your 
motel operator for assistance? You may. 

The motel operator listens patiently. 
She has, she says, heard this story many 
times. No, she does not know how I can 
get a Pacific Bell operator from that 
phone. She herself uses Pacific Bell at 
home and cannot make a long-distance 
call from the motel. She doesn’t know 
how things got to be that way. We de- 
cide that I should walk to Denny’s and 
use the pay phone. It’s raining today. 

Somewhere in this fabled land Judge 
Greene, having retired and left the 
bench, has no further use for the tele- 
phone and its conveniences. He trea- 
sures his place in history, though, be- 
cause he is secure in the knowledge that 
he performed a vast service for his coun- 
try by breaking up the finest commu- 
nications system that the world has ever 
seen or will ever see. 


DDJ 


To vote for your favorite article, circle inquiry no. 11. 
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486/Pentium Cross Platform Tools 





The Fastest 32-bit Code 


Microway has specialized in PC Numer- 
ics and x87 support since its founding In 
1982. In 1987 we_ introduced NDP 
Fortran-386, the first 32-bit Fortran that ran 
on DOS and supported the Intel and 
Weitek corpocessors. Today we produce 
i860 cards wth up to 200 megaflops of 
throughput which can be run in parallel as 
a one gigaflop computational server. Our 
compilers feature mainframe extensions 
plus unique optimizations like inlined intrin- 
sics, a "4+ 4" x87 stack model, loop unroll- 
ing and with the upcoming release of our 
Pentium code generator, optimal numeric 
support for Intel's latest CPU. The bottom 
line is our tools produce the best 32-bit 
code possible running on the largest 
number of platforms wih the front ends 
you need: Fortran-90/77 and C|IC+ +. 
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NDP Fortran-90...call for free demo disk and white paper! 


The key to optimal numeric performance 
is the use of the right tools. When it comes 
fo running scalar problems on scalar proc- 
essors, the difference between languages 
is small. However, wen RISC processors 
wth vector support are used, the language 
becomes important. In particular, if your 
programs spend most of their time manipu- 
lating data stored in amays, you need to 
use a language which improves vector 
efficiency and data flow by minimizing the 
number of accesses to memory. The di- 
chotomy between scalars and vectors has 
grow) worse as processors have become 
more dependent on caches for data ac- 
cess. Vectorization, the technique for opti- 
mizing accesses to data stored in caches, 
was developed in the late 70’s by Cray for 
the Cray 1’‘s Vector Registers. 


i860 Supercomputers 


Vectorization, as performed by tools like 
VAST, converts an F77 program into a new 
one which makes calls fo a "vector library." 
Fortran 90's Atay Syntax Notation results in 
vector code being inlined by the compiler 
directly. This feature is similar fo tensor nota- 
tion and produces compact readable 
code. It is the most significant "scientific 
addition" made to a procedural language 
in the last 20 years. Fortran 90 has also 
codified numerous F77 extensions, includ- 
ing dynamic arrays, case statements, struc- 
tures, modules and easy to use If, 
Whether you are running on a 486, Pen- 
tium, i860, or massively parallel Supercom- 
puter, Fortran 90 is the choice if numeric 
speed and portability matter. Call for our 
White paper on Fortran 90 today. 


508-746-7341 
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Microway’s NDP family of 32-bit compilers 
generate globally optimized mainframe 
quality code that runs on the 386, 486, 
Pentium and i860. They run on 32-bit 
operating systems such as OS/2, UNIX, 
solaris, Coherent, NT and DPMI/VCPI DOS 
Extenders. 


NDP Fortran’90 a complete Fortran-90 
which runs in conjunction with NDP Fortran. 
NDP Fortran” js a full F77 with F66, DOD, 
VMS and MS extensions. 

NDP C|C++ compiles K&R and ANSI C and 
is C+ + Release 2.1 compliant. 

NDP Pascal is a full ISO Level 1 Pascal with 
BSD extensions that can interface the NDP C 
runtime libraries. 

NDP Language Pricing 

DOS versions include a VCRMMM DOS Ex 
tender, DPMI interface layer, support for x87 
and Weitek coprocessors, NDPLink, NDPLib and 
GREX - our DOS graphics library. The Pentium 
release adds new code generation, royalty 
free DPMI and VCP plus symbolic debugging. 
DOS 386/486 VEISION........ cee $695/795 
DOS Pentium VEISION.........ccccccceeees $995 
OS/2 Developer's Pack includes IBM OS/2 
WorkFrame and Toolkit. These tools use the IBM 
Linker. Deduct $100 if you don’t need the 


Workframe. 386,486......ccccccccseccceecssecueeeeens $595 
PF NGM Plicvcuszncoiatesareanrdsenaabuniscd new aviaccuals $795 
UNIX 386/486 use the native tools and are 
available for SCO or IS€ UNIX............... $1195 
Coherent VEISION........ccccccccceccceccueeceeecuneess $295 
NDP Fortran-90..............cccccccccccecceeceeeeues $395 
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Gigacube™- Custom NFS 486 Worstation 
with your choice of QuadPuters or ArrayProXPs 
ONS: GINO TONY sens vaxecerainvscrsicnveancvacens $50K 


™ 
ArrayProXP -EISA Aray Processor - features 
a zero woit state 50 MHz 64-bit memory 
system. The 400 MBSec memory bandwath in 
conjunction wth 100 megaflop i860XP results 
in 28.96 Linpack megaflops, 94 megaflops 
doing dot products and 70 megaflops doing 
FFTs. The card bursts on the EISA bus at 33 
MBSec and holds up to 256 megabytes of 
PAI TOI sassctecatead inn iasrcvinsatinipimnscenodscanes $7995 


QuadPuter-860 - The word's most cost ef- 
fective Supercomputer. The QuadPuter includes 
four modules, each containing a 25 MHz i860 
and two megabytes of local memory. The 
modules plug into an ElSAcard that provides 32 
megabytes of shared memory. A single Quad- 
Puter has an aggregate throughput of 200 me- 
gaflops! With software ffOM... eres $9995 


Number Smasher-860 - our ISA 860 
card comes wih 8 or 32 megabytes. If in- 
cludes one NDP Language - 80 megaflops of 
HVOCUGHOUPSIONING GT JUST resnicescrccsissivosnneed $2995 


NDP Fortran*860 along with our CIC+ + 

and Pascal utilize advanced scalar code 
generation techniques to optimize the i860's 
numeric scalar PerfOrnMance. ccs $1995 


PPS-860 postorocessing scheduler, takes 
assembler ouftout and converts scalar opera- 
tions into pipelined operations running in dual 
instruction mode. Scalar speed ups in the 
range of 10 to 50% are COMMON..........666. $500 


VAST-II Vectorizer speeds up vector codes 
100 to 300%. Includes a library of 700 vector 
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Tower is the ideal solution to your 486/Pentium 
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UNIX, OS/2, DOS and Windows. What differenti- 
ates Microway towers is our ability to integrate the 
peripherals you need, including SCSI tape drives 
and CD-ROMs, network cards and high quality 
hard disk and graphics adapters. 486-BX systems 
are used worldwide performing demanding tasks 
from testing jet engines to searching for oil. Call 
today for our BX Series Catalogue. 
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MSE-160 - Free Text Search Engine ISA card 
processes 160 megabytes of data per second. 
Includes Text Retrieval SOPWAOIE....cccceeeees $950 
IMSL Microwoy compiled and validated ver- 
sion of the IMSL mainframe libraries, available 


for the 386/486 or i860, Complete 
PINMAGS eisccccrsassoartaticuumitaholatisnatenoe $2,000 
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Give Your Applications that 
“Do Anything Anytime” Control 


I n today’s world of advanced user 
interfaces, users are demanding more 
advanced control of their applications. 

It is no longer acceptable to wind your way 
through menus to accomplish one task, 
only to be forced to unwind your way back 
to accomplish the next task. We now want 
the ability to perform any 
task whenever we feel like 
it, no matter where we 
happen to be inside the 
program. 

We also want the ability 
to perform more than one 
task at a time. Consider a 
spreadsheet application; we 
might want to start a time 
consuming recalculation 
on one spreadsheet 
while we enter data into 
a second. In a word 
processor, we might want 
to print one document and 
repaginate a second while 
we enter text into a third. 

As users, these 
demands seem simple 
enough. Just give us a 
little more control. But 
as programmers, we realize that this type 
of control requires a very complex 
program design. 

At least it did until now! 


Develop Better 
Working Applications 


From Games to GUIs, Multi-C Makes It Easy to 
Develop Some Really Sophisticated Applica 


C4¥5.25” (43.5” 


(Requires DOS 2.0 or higher) 


Disk size: 
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LJ Please Send FREE Brochures ( Multi-c --- : 
[y Library Source ------- = To Order Please Call: 
(Source code for Multi-C Library) _ 


Enter the world of multithreaded 
programming, a technique that enables you 
to divide an application into multiple tasks (or 
threads), each of which executes independently 
from and simultaneously with other tasks. 
By using multiple tasks, it’s very easy to 
build advanced control mechanisms into your 
applications. Context is 
automatically maintained 
as control jumps from one 
task to another. And any 
number of tasks can 
be executing in the 
background while the 
user interacts with a 
foreground task. 

Multi-C supports 
multithreaded 
programming through 
a portable library of C 
functions. This small 
and efficient library is 
compatible with C and 
C++ compilers from Mix, 
Borland, Microsoft, and 
others. Because it 
contains no machine or 
environment specific code, 
the library may be used 
to develop applications for virtually any platform. 
To illustrate the power of Multi-C, we’ve included 
the complete source code for a video arcade game 
modeled after the original Space Invaders. 
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Adaptive Block 
Coding 


Ernie F. Deel 





Introduction 
by Tom Swan 


Mother said there would be days like this. We were trav- 
eling south in our sailboat on the Neuse River in North 
Carolina. It started to rain, then it poured. The temperature 
was in the upper 30s, and a 25-knot wind screamed its 
warning of worse to come. We were a teensy bit lost and 
needed to find a particular buoy with numbers that, at a 
distance, appear about as large as the letters in this sen- 
tence. As darkness approached, the waterproof seals on 
the binoculars decided to give up their struggle against rain 
and salt water, fogging the lenses and causing us to won- 
der what on earth had made us leave our house and warm 
fireplace to head south for the winter using this particular 
mode of travel. I half jokingly attempted to beam us up to 
the Enterprise, but alas, Scotty wasn’t listening. 

We may not have a transporter on board, but fortunately, 
we own a global positioning system (GPS) that can pin- 
point our location to within 10 meters (100 meters when 
the signal is scrambled by the military to foil its use by 
our enemies, which of course also foils its use by us). 
Thanks to the GPS, we were never actually lost, but we 
still needed to sight that buoy to avoid a dangerous shoal— 
going aground 100 meters off course is little better than 


hitting land two miles out of the way. Isn’t that always the 
case? Technology enhances, but never replaces, the sim- 
ple tools that led to the technology in the first place. De- 
spite our GPS, finding that buoy would mean the differ- 
ence between arriving in port and spending the night 
outside in the rain— not an attractive prospect. As you 
can imagine, searching for tiny, unlit, red-and- green mark- 
ers (some are only about three feet tall) in a driving rain- 
storm with fogged binoculars tests the limits of the brain’s 
pattern-recognition capabilities. 

Eventually, we found our marker and rounded the jetty 
into the harbor of a town with the unusual name of Oriental. 
I “fixed” the binoculars by disassembling them, managing 
in the process to crack one lens and partially defog the 
other. At least now we had a monocular we could use to 
continue to the next town, where we would purchase a 
new pair. 

Speaking of pattern recognition, I received the follow- 
ing article from Ernie F. Deel on a data-compression tech- 
nique that uses pattern-recognition analysis to achieve fast 
results and efficient compression ratios. I wish someone 
would build pattern-recognition algorithms into naviga- 
tional instruments. Maybe then, during the next storm, I 
could retire below, have a cup of tea, and let the boat find 
the darn buoys. 


eneric block coding is a data- 

encoding technique for subdivid- 

ing a data stream into multiple 

smaller blocks, which are then an- 
alyzed and encoded independently. The 
technique is adaptable to many pur- 
poses, but is ideally suited for com- 
pressing graphical images. Two of the 
most powerful image-compression 
schemes currently available —JPEG and 
fractal compression — both use block 
coding along with sophisticated data 
analysis and modeling. 

The algorithm presented here dem- 
onstrates basic block-coding techniques 
along with some relatively simple data 
analysis and modeling. The code uses 
the method to create tools for image 
compression and decompression. Im- 


Ernie Deel is an independent computer 
programmer and consultant with a 
background in engineering, CAD, and 
computer applications in a technical 
environment. He can be reached via 
CompuServe at 72027,3020. 
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ages compressed with this algorithm 
are comparable in size to images stored 
in the popular GIF format. 


The Algorithm 

Adaptive block coding (ABC) analyzes 
individual data blocks to identify pre- 
defined data patterns. Compression is 
achieved if a block contains a pattern 
that can be identified and encoded in 
fewer bytes than the original data. By 
using the most efficient, best-fit data 
pattern to encode each block, the al- 
gorithm adapts to changing conditions 
within the data stream, maximizing the 
compression level. Block size, number, 
and type of data patterns, as well as the 
encoding methods, can all be modified 
to experiment with new patterns or to 
better adapt the algorithm to a specific 
type of data. 

For work with graphical images, a data 
block is a set of pixel-color values from 
a small 2-D section of the image. As I 
will show later, however, block-encoding 
techniques are not limited to graphical 








2-D images. 1-D block coding can be 
used to further compress the 2-D output. 
I originally developed ABC encoding 
for an application where partial-screen, 
photo-type images were to be captured 
from video-camera displays and incor- 
porated into a database. The images 
were to be mixed with text from the 
database. Color was not essential, there- 
fore, I used VGA mode 12h (640x480 
resolution) with 16 gray-scale shades. 
Contrary to conventional wisdom, this 
mode can display good-quality gray- 
scale photographs. The mode’s high res- 
olution also allows excellent- quality text 
to be included with the image. The ba- 
sic algorithm presented here is limited 
to use with either color or gray-scale 
images in mode 12h, but it can be 
adapted to work with other modes. 


2-D Coding 

For the initial compression phase, the 
algorithm divides the image data into 
2-D, 8x8 pixel blocks. For each input 
block, three data items are generated: 
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e A block code, which identifies the gen- 
eral pattern type used to encode the 
block. 

e A pattern descriptor, which describes 
the specifics of the block using a sim- 
ple binary code. 

e Color coefficients, which define col- 
or magnitudes at critical points in the 
pattern. 


Separate arrays hold these three items, 
which can be stored in a disk file. 
Adding a file header and the image color 
palette completes the ABC disk-file 
structure; see Figure 1. To facilitate im- 


Example 1: (a) Horizontal-block 
code; (b) vertical-block code; 

(c) zigzag-left block code; (d) zigzag- 
right block code; (e) prime-color block 
code; (f) variable-length block code. 
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age decompression and reconstruction, 
the file header also contains the size in 
pixels of the original image and the size 
in bytes of each of the five sections of 
the disk file. 


2-D Data Patterns 

Six predefined 2-D block-data patterns 
are used. In addition, a block code of 
0 is used for blocks lacking a defined 
pattern that can be efficiently encoded. 
Based upon my experience with actu- 
al images, a very small percentage of 
blocks fall into that category. Other data 
patterns are easily added to those list- 
ed here. Example 1(a) shows a text rep- 
resentation of the horizontal block-code 
pattern. 

The numbers in the example indicate 
the row-oriented sequence in which the 
pixel block is analyzed for the existence 
of uniformly colored pixel groups. The 
program builds a binary pattern de- 
scriptor by assigning the preceding pix- 
el a code of zero for each pixel having 
the same color value. Unequal pixels 
are coded as 1. A complete pattern de- 
scriptor for an 8x8 pixel block therefore 
takes eight bytes. 

For each pixel encoded as 1, the pro- 
gram writes to the array a coefficient 
corresponding to the color of the pixel. 
To reconstruct the original block, color 
coefficients are either read from the 
array or duplicated as dictated by the 
pattern descriptor. Essentially, this is a 
binary-coded form of run-length en- 
coding. In photo-type images, very short 
runs of uniformly colored pixels are 
common and can be efficiently encod- 
ed. The block patterns in Examples 1(b) 
through 1(d) show variations on this 
theme using different analysis and en- 
coding sequences. 

Example 1(b) is the same as Exam- 
ple 1(a), but it examines the data 
stream using a vertical, column-oriented 
analysis. Example 1(c), on the other 
hand, analyzes the input data in a zig- 
zag pattern. 

The zigzag-block code efficiently en- 
codes blocks dithered with pixels of al- 
ternating colors. “Dithering” is a tech- 
nique used in graphics software to 
create apparent colors. For example, a 





Figure 1: ABC file structure. 








simple dithering scheme might alternate 
red and yellow pixels to create the ap- 
pearance of orange. Dithering is also 
heavily used by analog-to-digital con- 
verters such as scanners and video- 
capture cards. Signal fluctuations, round- 
off errors, and other phenomena within 
the hardware and software can also pro- 
duce a dithering effect. 

The block code in Example 1(d) is 
similar to that in Example 1(c), but the 
zigzag path begins at the upper right. 
Sometimes, simply analyzing the data in 
the other direction can produce more 
efficient compression. 

The numbers in the block code of Ex- 
ample 1(e) represent actual hexadeci- 
mal color values. At first glance, there 
doesn’t appear to be a consistent pat- 
tern, but by counting like-colored pix- 
els, you find that 26 out of 64 pixels 
have the color value OA, called prime 
color. The pattern can be encoded us- 
ing a simple binary code. For example, 
following a horizontal row-oriented path 
similar to Example 1(a), every prime- 
colored pixel is encoded as 0. Nonprime 
colored pixels are encoded as 1. Only 
the prime-color coefficient and the col- 
or values for nonprime pixels are writ- 
ten to the output. 

As in the preceding pattern, Exam- 
ple 1(f represents actual pixel-color 
values. Again, no pattern is obviously 
consistent. Upon close inspection, 
though, all the pixels evidently have 
one of four color values: 03, 05, 07, or 
09. Since only four different colors are 
present, the colors in this block can be 
encoded using only two bits instead of 
the usual four required to encode the 
full set of 16 colors. Each of the four 
colors is assigned a 2-bit code. The pat- 
tern descriptor then becomes a simple 
listing of 2-bit codes that describe col- 
or values of pixels in a row-oriented 
fashion. The four-color coefficients are 
output in the same sequence as the 2- 
bit codes, cutting the size of the block 
almost in half. 

Additional block codes reflect actual 
numbers of colors found within the im- 
age block. Table 1 lists the bits per pix- 
el used to encode the colors within the 
pattern descriptor. Block codes 14 and 
15 are not used. 


Table 1: bits per pixel for color 
encoding. 
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Pattern Analysis and Selection 

For each pixel block, the program cal- 
culates the final encoded block size 
for each of the six basic patterns. En- 
coded block size is measured in terms 
of the equivalent number of noncom- 
pressed pixels. This provides a con- 
sistent method of comparing different 
patterns, including the nonencoded 
pattern, 0. The most efficient, best-fit 
pattern is obviously the one that pro- 
vides the smallest encoded-block size. 
Thanks to the simplicity of the data 
patterns, compression is relatively fast 
even with this simple, brute-force 
analysis. 


One-dimensional Coding 

After the 2-D compression phase, the 
data has lost any possible geometric 
interpretation. It can now only be 
viewed as a one-dimensional sequence 
of bytes. For reasons that are not clear 
to me, a significant number of short 
runs of bytes typically occurs in each 
of the three output arrays. To take ad- 
vantage of this redundancy, I created 
a one-dimensional block-encoding 
algorithm that accepts as input one of 
the 2-D data arrays. If any additional 
compression is possible, the input ar- 
ray is returned in compressed format; 
otherwise, the array is returned un- 
changed. 

The 1-D block-encoding algorithm 
closely parallels the 2-D block-en- 
coding algorithm. The input data 
stream is first subdivided into 1-D 
blocks of 16 bytes each. Each block is 
then analyzed for the presence of a 
simple pattern. As in the 2-D case, the 
following three items are written to the 
output for each block: 


e A block code, which identifies the gen- 
eral pattern type used to encode the 
block. 

e A pattern descriptor, which defines 
actual pattern specifics for the block 
using a simple binary code. 

e Byte or character coefficients, which 
define byte or character values at crit- 
ical points in the pattern. 


Pattern Descriptor: 
1001::10100110110 


ed 


9D 36 


Block Code 
Pattern Descriptor 
Byte Coefficients 
Original Block Size 


: 1 (2 bits) 

: 9D 36 

: FD 05 0B 04 07 AA 08 15 
: 16x8=128 bits 
Compressed Block Size: 2+(2x8)+(8x 8)=82 bits 


Compression Ratio : 0.64 





Figure 2: Sample 1-D encoded data. 
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For 1-D coding, only two data pat- 
terns are used. A pattern code of zero 
represents blocks that do not contain an 
encodable pattern. 1-D block codes 0, 
1, and 2 are therefore encoded using 
only two bits. 

Again, a binary pattern descriptor is 
used. Similar to several of the 2-D pat- 
terns, a byte that repeats the preceding 
byte is coded as 0; unequal bytes are 
coded as 1. Only the nonrepeating bytes 
are stored. The original block is recon- 
structed by either reading bytes from a 


By using the 
most efficient, - 
best-fit data 
pattern to encode 
each block, the 
algorithm adapts to 
changing conditions 
within the data 
stream 





byte-coefficient array or duplicating the 
previous byte as dictated by the pattern 
descriptor. Figure 2 shows an example 
of a data block encoded according to 
the 1-D algorithm. As with the 2-D 
prime-color pattern, the idea here is to 
encode the most common (prime) char- 
acter/byte found within the block (OA, 
in this case). 

Following compression, the data ar- 
ray is composed of three different sec- 
tions, closely paralleling the segmenta- 
tion of the 2-D output. To facilitate 
decompression, the first two bytes in 
the array indicate the total number of 


Total 1-D blocks 
in array (2 bytes) 


Section 
Length 
(bytes) 


nm Block Codes 





Section i 
Length 


Section - Bytes Coefficients 
Length 


Pattern Descriptors 





Figure 3: 1-D compression output 
array. 


1-D blocks. A decompression program 
can use that information to determine 
whether or not a section has been com- 
pressed by 1-D coding. 

Figure 3 illustrates the output array 
after 1-D compression. The first two 
bytes in each section of the array in- 
dicate the total length of the section. 
Based upon my experience with ac- 
tual images, the 1-D compression 
phase typically improves the overall 
compression ratio by about 10 percent 
or more. 


The Source Code 

The included ABC source code dem- 
onstrates both the use and develop- 
ment of reusable software components 
with Microsoft’s MS-DOS Basic. The 
source code will also run with minimal 
changes under Visual Basic for Win- 
dows. I used components from Cres- 
cent Software’s Graphics Workshop to 
build the ABC compression and de- 
compression modules. 

The program COMP.BAS is the ABC 
compression-subroutine module, while 
DECOMP.BAS contains the ABC de- 
compression subroutine; both programs 
are available electronically; see “Avail- 
ability,” page 3. PCX2ABC.BAS in List- 
ing One (page 148) demonstrates how 
to use the compression module. The 
program displays a PCX image, simu- 
lating video-camera output. The image 
is captured from the screen, compressed, 
and stored in a disk file. Listing Two 
(SHOWABC.BAS, page 148) demon- 
strates ABC decompression. The pro- 
gram simply redisplays compressed files 
produced by PCX2ABC. 

The modules take advantage of Ba- 
sic’s built-in memory management to 
allocate dynamic storage arrays. As im- 
plemented, the sample programs’ ar- 
rays are limited to 64K; therefore, it 
may not be possible to compress some 
larger images with the programs list- 
ed here. Basic fully supports the use 
of huge arrays (>064K), but I didn’t 
need that capability for my applica- 
tion. If available storage is exceeded, 
the compression module returns a 
negative number for compressed im- 
ASe SIZC. 

Listings Three (COMP.DCL, page 149) 
and Four (DECOMP.DCL, page 149) con- 
tain function prototype declarations for 
COMP.BAS and DECOMP.BAS. These 
files must be included in programs that 
use the compression and decompres- 
sion modules. 


DDJ 


(Listings begin on page 148.) 


To vote for your favorite article, circle inquiry no. 12. 
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CONFERENCE 
IS COMING TO BOSTON 


DESTINATION: BOSTON EXPERTS’ INSIGHTS FIRSTHAND 


The world’s largest conference and exhibition dedicated to 
microprocessor- and microcontroller-based development 

returns East this spring for a command performance. Even if you 
attended our East Coast debut in Atlanta last year, Boston is 
where you should be April 19-21, 1994 — for the second 

annual EMBEDDED SYSTEMS ww 
CONFERENCE EAST. 





Get direct access to dozens of today’s top experts in embedded 
development, including: 











@ Paul Ward and Stephen Mellor, creators of 
the Ward-Mellor methodologies that brought 
CASE to real-time embedded systems 

@ Larry Constantine, co-author of the defini- 
tive text, Structured Design 

@ Plus many more 


WE SPEAK ALL THE 
LANGUAGES 


The EMBEDDED SYSTEMS CON- 
FERENCE EAST will help you hone 
the technical and project management 
skills required for the entire embedded 
process. If you want to improve design, 
write more efficient code, devise more 
effective project management strategies, 
and see the future of embedded develop- 
ment more clearly, we’ve got what 

you need. 


TARGETED PRODUCTS 
AND SERVICES 


See the largest dedicated exhibition of 
embedded development tools and utili- 
ties, talk to representatives from more 
than 100 leading companies, and try the 
latest in: 
@ compilers/cross compilers @ in-cir- 
cuit emulators @ logic analyzers 
@ single board computers ® microproces- 
sors/ microcontrollers ® debugging tools @ real-time operat- 


TIPS, TRICKS, ing systems @ cross assemblers @ simulators ® and more... 
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EMBEDDED SYSTEMS CONFERENCE EAST 
April 19-21, 1994, Hynes Convention Center, Boston, MA 
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Mix and match dozens of hands-on programming and 
methodology workshops, lectures, and tutorials on topics 

like these: 

@ Design methodology # Debugging @ Languages # Networks 


@ Chip programming Hardware interfacing @ Digital signal 
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UNDOCUMENTED CORNER 


RINGO: 
VxDs on the Fly 


Alex Shmidt 








Introduction 
by Andrew Schulman 


A key feature of Microsoft’s forthcoming “Chicago” operat- 
ing system is “plug-and-play,” a specification that, once ful- 
ly implemented, will allow completely dynamic configura- 
tion of a PC, without user intervention or rebooting the system. 
While your Windows program is running, drive letters may 
come and go, the screen resolution may change, and new 
device drivers may come on line or suddenly become un- 
available. This should make for interesting behavior as ap- 
plications learn to adjust themselves to the new regime. (GO 
PLUGPLAY on CompuServe has more about plug-and-play.) 

In Chicago, a key part of plug-and-play is the ability to 
dynamically load and unload virtual device drivers (VxDs) 
on the fly. This is provided by a VxD called VXDLDR.386, 
which has already been released as part of Windows for 
Workgroups 3.11. It appears that only specially marked 
VxDs can be dynamically loaded and unloaded. 

In this month’s “Undocumented Corner,” Alex Shmidt 
shows another way to achieve dynamic VxD loading and 
unloading, without using VXDLDR, and even without a 
VxD file. Actually, Alex provides a general technique for 
calling any 32-bit Ring 0 (privileged) code from a normal 
Ring 3 (under-privileged) Windows program. In the May 
1993 Microsoft Systems Journal, Matt Pietrek used callgates 
to access 16-bit Ring 0 code. Alex extends Matt’s technique 
to 32-bit Ring 0 code, and then shows how to take some 
of this code and link it onto the VxD chain. Thus, the VxD 
code need not reside in a Linear Executable (LE) .380 file. 
Alex keeps his VxD code in a normal Windows DLL. 

This really works! For example, after starting Alex’s sam- 


ple GATEVIEW program, his newly created RINGO VxD 
shows up in the output from my VXDLIST program (see 
the December 1993 “Undocumented Corner”). This works 
not only in Windows 3.1 but also in a prerelease of Chica- 
go. Of course, VxDs dynamically installed after the system 
has started will not receive initialization messages such as 
SYS_DEVICE_INIT. (VXDLDR solves this with new mes- 
sages such as SYS_DYNAMIC_DEVICE_INIT.) 

Alex refers to this dynamic VxD facility as RINGO, in ob- 
vious reference to Ring 0, and perhaps also in tribute to 
Ringo Starr. RINGO relies on several pieces of undocu- 
mented functionality. In particular, its ability to add to the 
VxD chain at run time depends on knowledge of the Vir- 
tual Machine Manager (VMM) INT 20h dynamic linker. I 
also found myself relying on this in my generic VxD (see 
MSj, February 1993). But Alex has uncovered an odd side- 
effect of the VMM dynamic linker that can be used to re- 
trieve the root of the VxD chain; this seems a lot cleaner 
than the technique I used in the December 1993 DDJ. Clear- 
ly, knowledge of VMM’s INT 20h dynamic linker is useful. 

Alex also uses an undocumented parameter to the _A//o- 
cate_GDT Selector service, and uses (though does not de- 
pend on) an undocumented Windows service for getting a 
selector to the Local Descriptor Table (LDT). This backdoor, 
accessible via INT 2Fh AX=168Ah, is described in Chapter 
1 of Matt Pietrek’s Windows Internals (Addison-Wesley, 1993). 

For future columns, I’d love to hear from any reader who 
might be able to write something on Windows multimedia 
internals (MMSYSTEM.DLL), or describe how “OS/2 for Win- 
dows” works. Contact me on CompuServe at 76320,302, or 
in the new “Undocumented Corner” area on CompuServe 
(GO DDJ). 





major advantage of protected- 
mode operating systems is their 
robustness. Running at the proces- 
/ "sor’s highest execution- privilege 
level, the operating system ensures its 
exclusive access to vital computing re- 
sources. The simple fact that certain ma- 
chine instructions are unavailable to ap- 
plications makes it difficult for them to 
fool around with vital system areas and 
violate the system integrity. 
Unfortunately, this user-supervisor 





Alex works for a large financial com- 
pany in New York, where he develops 
multiplatform network software. He’s 
been doing low-level Windows pro- 
gramming since 1991. Alex can be 
reached on CompuServe at 73302, 060. 
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separation also presents a major prob- 
lem: Because normal applications aren't 
allowed low-level access to the system, 
any program that needs such access 
must be built with a special set of pro- 
gramming tools, and can only be load- 
ed in a special way, usually requiring a 
reboot of the whole system. 

Although often described as some- 
thing less than a full operating system, 
Microsoft Windows 3 really does con- 
tain a complete operating system. It’s 
presented by the Virtual Machine Man- 
ager (VMM) and a set of Virtual Device 
Drivers (VxDs), whose primary purpose 
is to preemptively multitask Virtual Ma- 
chines (VMs), visible to us as DOS box- 
es. The VMM and VxDs run 32-bit code 
in the flat memory model at the most- 


privileged level of the 80x86 CPU, of- 
ten called Ring 0, which refers to the 
innermost circle of a concentric ring di- 
agram. The “virtualization” introduced 
by VxDs depends on their ability to ex- 
ecute any CPU instruction. 

On the user-mode side of the fence, 
we find native Windows and DOS pro- 
grams. They run at the least- privileged 
level, Ring 3 (Windows 3.0 programs 
ran at Ring 1) and have no control over 
their privilege level. Still, many Windows 
programs need to do some low-level 
work (for port I/O and the like) while 
maintaining a high level of performance. 
This is why so many application instal- 
lations add a VxD to the SYSTEM.INI 
file. For example, Microsoft’s recent C 
compilers install several VxDs. 
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Without Microsoft's VXDLDR, there 
usually isn’t a way to install and re- 
move a VxD while Windows is run- 
ning. VxDs reside in the linear exe- 
cutable (LE) files, and their presence is 
under complete control of the LE load- 
er, which only runs when Windows 
bootstraps. When a typical installation 
ends, a message pops up indicating that 
we need to restart Windows to have it 
load the new VxDs. 

When creating a VxD, you're limited 
by the toolset distributed with the De- 
vice Driver Kit (DDK), which contains 
a special version of assembler (MASMS5), 
the linker LINK386 for producing LE 
files, and some other tools. This prob- 
lem has been lately addressed in sever- 
al packages for writing VxDs with 32- 
bit Watcom C or Microsoft C. But these 
VxDs still can only be loaded at Win- 
dows startup. 

This article shows how to overcome 
these limitations, using an installable 
VxD called “RINGO.” RINGO is actually 
a dual-faced program, running in both 
Ring 3 and Ring 0. RINGO is a Windows 
DLL, but provides a technique equally 
applicable to the protected-mode DOS 
world. As you'll see, it used some un- 
documented VMM functionality. RINGO 
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Figure 1: GATEVIEW displays information such as the page directory and the 


stream of VMM events. 


: 0044C000 0084C000 00000000 - OOSFFFFF U 
1: 0345000 007A5000 00400000 - OO7FFFFF PWA U System 
1/2: GO03A6000 O07A6000 00800000 - OOBFFFFF PWA U System 
3: 00347000 007A7000 O0CO0000-O0FFFFFF PW  § U System 
: 0044D000 0084D000 980000000 - 803FFFFF PWA U System 
: G039C000 O07SC000 80400000 - SO7FFFFF PWaA U System 
- 0039D000 0079D000 80800000 - SOBFFFFF PWA U ster 
: GO39E000 007SE000 PW U $ 


80C00000 - SOFFFFFF 


¥MM Events 
¥VM 805D1000 Device 0000000C Func 00000E50 
Device 0000000D Func 00000650 
Device D000000A Func 00000E50 
Device O000000C Func 00000E50 


Device 0000000D Func 00000E50 
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works in both the debug and retail ver- 
sions of Windows 3.1. Besides, the func- 
tionality RINGO relies upon is so cen- 
tral to Windows that it will likely remain 
in the future versions. Indeed, RINGO 
works fine with the August 1993 prere- 
lease of Chicago. 

To give you an idea what RINGO is 
capable of, I wrote a sample program, 
GATEVIEW. As seen in Figure 1, GATE- 
VIEW can display both CPU and oper- 
ating-system internal data, like the con- 
tents of the Page Directory, GDT and 
LDT, the VMCB (see “Undocumented 
Corner,” January and February 1994), the 
VxD list, and the stream of VMM events. 

RINGO resides in a regular Win16 
DLL, has the standard USE16 code seg- 
ment _TEXT produced by the C com- 
piler, with LibMain, WEP, and export- 
ed functions. To the Windows loader it 
looks like any other DLL. What makes 
RINGO a VxD is the USE32 segment 
_GATESEG, with which it’s linked. The 
code in this segment executes at Ring 
0, communicates with the VMM, and 
provides to the Ring 3 part a service 
function, SeeYouAtRingO (see Listing 
Four, page 151). When GATEVIEW.EXE 
calls the exports, RINGO steps down to 
Ring 0 and retrieves tons of internal in- 




























typedef DWORD (FAR PASCAL * CATEPROC) (WORD sve, WORD cnt, DWORD extra); 


i ES; bytes = 2 DWords j 


31 16 18... g 
Lilia 
OFSSET 31... 16 TYPE 


_GATESEG 


SELECTOR 


OFFSET is..9 


28h 1 { Flat Model Code Selector} 





Figure 2: RINGO callgate descriptor for the SeeYouAtRingO function. 
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formation for GATEVIEW, usually avail- 
able only to a system-level debugger. 
RINGO also inserts itself into the VxD 
chain and posts messages back to GATE- 
VIEW, whenever it gets called asyn- 
chronously by the VMM. 

Although the code for RINGO and 
GATEVIEW is too long to reprint here in 
its entirety, excerpts from CALLGATE.H, 
RINGO.C, RINGO.INC, and CALL- 
GATE.ASM are shown in Listings One 
through Four. The complete source code 
is available electronically (see “Avail- 
ability,” page 3). 


Using Callgates 

RINGO does not call Ring 0 directly, as 
this would invite a general- protection 
(GP) fault. Instead, RINGO makes ring 
transitions via callgates. 

Callgates are a native part of the CPU 
protection mechanism, performing ring 
transitions (somewhat slowly) in just one 
machine instruction. They are one of the 
several types of gates designed to allow 
less- privileged applications to access 
more-privileged operating-system ser- 
vices. Callgates are special entries in a 
descriptor table, and they have associ- 
ated selectors. Unlike segment descrip- 
tors, which use bases and limits, call- 
gates are built around 16:16 or 16:32 far 
pointers to entry points at Rings 0, 1, or 
2. When the operating system wants to 
provide a strictly controlled interface to 
its service at that entry point, it creates 
a callgate descriptor and makes its se- 
lector available to applications. When an 
application targets the callgate selector 
in the far call or jump instruction, the 
ring transition occurs. For example, OS/2 
1.x relied heavily upon callgates to pro- 
vide most DOSCALL kernel services. 

It's worth mentioning that Windows 
ignores callgates and instead uses a 
completely different (and, presumably, 
faster) ring-transition scheme that forces 
the application code to generate an ex- 
plicit or implicit fault, which VMM traps 
and dispatches to the appropriate han- 
dler. For example, the VMM Jnstall_ 
VS80_Break_Point service plants a byte 
63h in user code; this corresponds to 
an illegal ARPL instruction. When a pro- 
gram running in V86 mode executes the 
illegal instruction, a fault is generated 
that VMM interprets as a signal to dis- 
patch control to a Ring O handler. 

Let’s avoid duplicating the Intel man- 
uals and take a look at how RINGO con- 
structs its callgates; see Figure 2. 

Each Virtual Machine in Windows has 
its own LDT. This means that when a task 
switch occurs and the current VM goes 
to sleep, all of its LDT selectors become 
meaningless until the next time this VM 
is scheduled. Since RINGO is an equal- 
opportunity employer, nice to all VMs, it 
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(continued from page 134) 

creates a callgate to the SeeYouAtkingO 
service in the global descriptor table 
(GDT), available to everybody. 

When the Windows loader brings 
RINGO.DLL into memory, it knows noth- 
ing about USE32 segments. Just as it al- 
ways does, the loader allocates a mem- 
ory block for GATESEG from the System 
VM global memory pool and allocates a 
USE16 code selector that maps it. At this 
point, RINGO treats _GATESEG as just 
a memory object. RINGO translates the 
16:16 far address of the SeeYouAtkingO 
function within the object into the lin- 
ear address and inserts it into the gate 
descriptor’s OFFSET field. This 0-based 
offset needs a selector, mapping the en- 
tire 4-gigabyte address space. RINGO 
borrows the flat-model code selector 
(28h) from the VMM and inserts it into 
the descriptor’s SELECTOR field. This al- 
lows RINGO to make near calls to the 
VMM, as is expected of a VxD. 

Although callgates literally open doors 
to interlevel calls, the CPU still verifies 
an application’s access rights to the gate 
itself. That’s why RINGO sets the call- 
gate descriptor’s DPL and its selector’s 
RPL to 3. It sets the system bit to 0 to 
let the CPU know what kind of de- 
scriptor it’s creating. Since See YouAt- 
RingO is a 32-bit function, RINGO sets 
the type field to 12 Git would be 4 for 
16-bit code). SeeYouAtRingO executes 
when the Ring 3 code in RINGO.DLL 
calls a function of type GATEPROC, 
whose prototype in CALLGATE.H (List- 
ing One, page 150) accepts two WORDs 
and one DWORD as parameters, re- 
sulting in two DWORDs total, and 
RINGO sets the DWORD parameter 
count field to 2. Finally, RINGO per- 
manently sets the descriptor’s present 
bit, because VxDs can’t be swapped out 
of memory. 

As usual, the callgate selector is an 
index to its descriptor in the GDT. When 
the Ring 3 code in RINGO makes a far 
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call, the CPU sees that the CS register 
has been loaded with the callgate se- 
lector, and loads SS:ESP with the stack 
of the SeeYouAtRingO entry point’s priv- 
ilege level from the task state segment 
(TSS), copies the number of DWORD 
parameters specified in the gate de- 
scriptor from the caller stack, and trans- 
fers control to SeeYouAtkingO at Ring 0. 
The CPU switches stacks to ensure that 
the stack segment’s DPL will be equal 
to the CPL when the instructions ma- 
nipulating the stack get executed from 
Ring 0. Otherwise, a GP fault would oc- 
cur. This is why there are Ring 0, 1, and 
2 stacks specified in the TSS; the CPU 
is thus always ready for a ring transition 
between any two levels. Figure 3 shows 
the stack layout. 

When SeeYouAtRingO is about to re- 
turn to Ring 3, the CPU cannot remem- 
ber that it’s getting back from a gate. To 
restore the stack properly, SeeYou- 
AtkingO uses an RETF<# of bytes> in- 
struction. Interestingly enough, it clears 
the stack frames of both rings, which 
means that callgate procedures are typ- 
ical Pascal calling convention functions 
(the called function pops the stack). 

How does RINGO modify the GDT? 
Since both the Windows API and the 
DOS Protected Mode Interface (DPMD 
know only about LDT segment de- 
scriptors, RINGO uses the VMM _Allo- 
cate_GDT_Selector service. If you just 
construct your callgate DWORDs and 
call this API, though, you'll get back 0. 
Doesn’t it like system descriptors? But 
wait a second. How does VMM itself get 
nonsegment descriptors, such as inter- 
rupt gates, for example? The answer is 
that the undocumented flag 20000000h 
must be passed to _Allocate_GDT_ 
Selector to make the function do what 
we need. Sure enough, the DDK doc- 
umentation for the _Allocate_GDT_ 
Selector flags parameter states: “Speci- 
fies the operation flags. This parameter 
should be set to 0.” Ignore this advice 


(GDT_Gate) (WORD svc, WORD GateW, DWORD GateDw); 


Ring 3 stack 


Gatew 


word ptr GateDw+2 
word ptr GateDw sik 





Ring 0 stack 
ee 


jold SS | 


dword ptr GateDw 


SSO:ESPO 


return EIP 


Figure 3: Stack frame during a call to SeeYouAtRingO through the callgate. 
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to get a GDT callgate. 

Okay, that’s a key piece, but we’re 
still at the improper ring to call the 
VMM. So how do we get to the proper 
ring? Personally, I prefer using a tiny 
VxD, CALLGATE.386, whose only job is 
to create and destroy callgates on be- 
half of applications. 

However, this requires that CALL- 
GATE.386 already be installed. There- 
fore, ] made RINGO a totally indepen- 
dent and self-loadable VxD. I modified 
the technique presented in Matt Pietrek’s 
article, “Run Privileged Code from Your 
Windows-based Program Using call- 
gates” (MSJ, May 1993). 

To launch itself into the Ring 0 orbit, 
RINGO creates another callgate, this time 
in the LDT. It uses Microsoft’s undocu- 
mented “MS-DOS” extension to DPMI, 
accessible via INT 2Fh AX=168Ah, to get 
a selector that maps the LDT. Just like 
KRNL386.EXE in Windows, RINGO uses 
this to write directly to the LDT, build- 
ing the callgate for another Ring 0 flat- 
model function, Ringolnit (Listing Four), 
which initializes the VxD environment. 
When constructing the callgate descrip- 
tor, I hardcoded selector 28h (see 
GetLdtkingOCallGate in RINGO.C, List- 
ing Two, page 150). Neither that selec- 
tor value nor the LDT callgate approach 
are needed with CALLGATE.386. 

Note that Microsoft’s DPMI extension 
sets the carry flag, indicating an error, if 
called from outside the System VM. To 
use the RINGO approach with protected- 
mode DOS programs, you'll have to use 
some other method for allocating LDT 
callgates, such as CALLGATE.386. (An- 
other method involves the Intel SLDT 
and SGDT instructions, which are not 
privileged.) 

If you compile RINGO.C with CALL- 
GATE_386 switch defined, RINGO will 
get the callgate for Ringolnit from CALL- 
GATE.386. Unlike RINGO, CALLGATE 
386 is a conventional VxD. It implements 
an INT 2Fh AX=168Ah DPMI-extension 
interface to communicate with applica- 
tions, and thus doesn’t need a VxD ID. 
(Given the current confusion surround- 
ing VxD IDs, you might want to think 
about giving your own VxDs DPMI ex- 
tension interfaces rather than VxD pro- 
tected-mode API interfaces.) 

So what happens when LibMain (see 
Listing Two) calls the far pointer with 
the gate selector in it? Because of the 
callgate, the next instruction the CPU 
executes is the PUSH EBP in Ringolnit 
at Ring 0, somewhere at address 28h: 
80xxxxxx. Having stepped into Ring 0, 
RINGO is going to make extensive use 
of VMM services, and needs to set up 
several things to be a good neighbor. 
Ringolnit starts by building the stack 
frame, partially set by the CPU. Our 
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C CODE FOR THE PC 


source code, of course 


GraphiC 7.0 (high-resolution, scientific plots in color & hardcopy, contour plots, device independence) . . . . 2... ese ee ee ees $370 
X/DOS and Xt/DOS (Xlib with X client and Xt toolkit for DOS; port X code to DOS; Xt/DOS requires X/DOS and 32-bit compiler) . . each $300 
ZIP Image Processor & Victor Image Library Version 2.2 (brightness, contrast, merge images, TIFF/GIF/PCX/bin, HP ScanJet support) . . $290 
The Snooper (Ethernet protocol analyzer for Novell NetWare and LAN Manager Networks capture packets; real-time display) ...... $275 
Embedded BIOS (full-featured, real-time input/output system; PC, XT, AT; for example, 80186 with 8259 interrupt controller)... .... $260 
C/C++ Libraries by Code Farms (persistent C structures, ER models, dynamic arrays, database functions, Jolt Award winner; specify C or C+ +)$250 
TurboTX (Release 3.0; HP, PS, dot drivers; CM fonts; LaTRX; MetaFont) . . ©. 1 1 1 1 ee ee ee ee ee ee ee ee ee es $250 
Rogue Wave tools.h-+-++ or math.h++--+ Class Library (extensive docs)... 6 6 ee ee ee ee each $240 
Crusher! Uo loulb oo Pa oa data compression for network transfer; beats PK & LH on binary; directory trees; portableC) ...... $215 
COMM-DRV (complete interrupt-driven serial communication libraries & device drivers; fullsource) . . 2. ee ee ee ee ee es $155 
TE Editor Developer’s Kit Ver. 3.0 (full screen editor, undo command, multiple windows; with Word Processing $230) .......... $155 
Minix Operating System (Version 1.5; Unix-like ikea lage includes manual; specify 5.25” or 3.5” diskettes) . . 2. 2... 2 ee ees $150 

; Intel or Motorola hex format; macro preprocessor) ........+.4.e-. 150 


Moby Crypto ae DES, Secure Hash, UFC, MDs, Crack 4.1, Lucifer, IDEA, VCR+, a OF integer packs, tutorials, more; not for export) . . eae 


Lisp for DOS (Kyoto Common Lisp and CLISP; KCL includes Lisp-to-C translator for building mixed Lisp/C programs) .........- 140 
Ibrow (Version 4.1; programmer’s Windows-based editor; large files, help, undo/redo, drag-n-drop, function & type tags)... .---.-.-- $135 
Booter Toolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) ..... . $120 
SCM (portable Scheme in C, IEEE standard, includes JACAL symbolic math package; SCM-4D0/SLIB-IDS/JACAL-1A3) ........ $100 
PC/IP (CMU/MIT TCP/IP for PCs; Crynwr drivers, NFS server, Bdale mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . . $100 
DA (disassembler for Microsoft’s New Executable fe binary files including Windows .exe, .drv, dll,and fit)... ....-.-..-+.-- $95 
Script Interpreter (a command script rea whe for DOS-based systems; C-like script language; lots of features)... ... +--+ ees $90 
CELP 3.2c (Federal Standard 1016 Code Excited Linear Predictive voice sampling and encoding; voice over 4. ; Unix code)... 4.5% $80 
CPPCOMM (C++ serial communications class library for DOS, Windows, OS/2, and NT; includes X/Y/Zmodem) . . .........-. $75 
ET Neural Net (back error propagation and Kohonen; specify DOS text, DOS VGS, or Windows)... . - - - ee ee eee ee es $75 
FlexList (doubly-linked lists of arbitrary data with multiple access methods; specifyCorC++) . . - 6 6 ee eee ee ee ee ee es $65 
Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic) . . 2... 2. ee ee ee ee ee eee $60 
Coder’s Prolog (Version 3.0; inference ra for use with C programs) . . 2. 2 1 6 ee ee ee ee ee ee ee we ee ee ee $60 
PCCTS Version 1.10 (Purdue Compiler Construction Tool Set; like YACC and LEX together with lots of additional features) ...... . 60 
Container Lite V 1.82 (C++ & FLC wrapper emulators; portable, persistent containers of arbitrary data including pointers). ....... $50 
ay Cas precision floating point arithmetic and functions; includes BCD conversion)... - 6 ee ee eee ee ee es $50 
EZCalc (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easilyextended) ....... $50 
Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption) . . . 6. 6 ee ee ee ee ee es $50 
CLIPS Version 6.0 (rule-based expert system generator, Windows compatible; hardcopy manuals additional) . . ~~... ++ + ee ees $50 
SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories) . © © 6 ee ee eee ee es $50 
OBJASM (convert .obj files to .asm files; output is MASM sce oes wt ee ee OB eee Ae ee a Sue Be le a le $50 
Editor Pack (20 public domain editors; micromacs 3.12, Stevie, Ivis, Moke, mg2a, DTE, Jove, Origami, CE & GRIEF). ......... $50 
Exceptions for C (Ada-like exception handling for C Ly Aeon exceptions for any block; exceptions can be reraised) ....-...-.-- $45 
DES Encryption & Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; not forexport) ......... $40 
Database Pack (9 databases — simple to complex: isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, POSUQTES) os 6. wesw ee ee $35 
COP (poor man’s C++; C macro package which implements C+ + in 3 Lee ede ae wee oe oe ce oe we we we oo oe SG $35 
OCT (Object C Translator, essentially Brad Cox’s Objective-C Version4) «2 6 6 1 6 ee ee ee ee ee ee ee ee es $35 
RXC & EGREP Version 2.0 Sori om Expression oe and Pattern Matching; finite state machine from regular expression) ...... $35 
Bison & BYACC (YACC workalike parser generators; documentation; includes Cand C++ grammars)... . 1 ee ee ee ee ee $35 
Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) $30 
REGX Plus (Version 3.0, search and replace string manipulation routines based on compiled regular expressions) .....-+-+-+-+-+-- $30 
GNU Awk & Diff for PC (both programs in one pac > Ces ee we he oe ee oe ee eos ee eee $30 
Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter isincluded) ....... $30 
Crunch Pack (30 file compression & expansion programs; now includes portable ZIP) . © 6 6 6 6 ee ee ee ee es $30 
OORT (C++ ray tracing code from the book by Nicholas » ee re eee oe ee eee ee ee ee ee $30 
OEmacs (full GNU Emacs for DOS and Windows DOS box; C++ support, etags++,lotsof.elfiles) . 2... 6.6 eee ee eee $25 
CT ak Version 2.22d (robust MS-DOS multitasking kernel; C functions run as light-weight processes; mailboxes, interrupts, pipes, etc.) $25 
PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; includes hardcopydocs) ...-- +--+ +++ +e $25 
FLEX Version 2.4.3 (fast lexical analyzer generator; new, improved LEX) . . . 2 6 1 6 ee ee ee ee ee ee $25 
GNU RCS (FSF’s version of the Revision Control System; like Unix’s SCCS only better; keeps track of software development). ...... $20 
Data 

Moby Thesaurus II (6,000 root words, 2.5M synonyms, "common sense”, concept related searches) . . - 6 - - ee ee ee ee es $500 
Moby Pronunciator II aaa words & phrases encoded with full IPA pronunciation & emphasis points)... . . - +e eee ee ees 
Moby Part-of-Speech II (230,000 words and phrases described zi prioritized part(s)-of-speech) . 2. 6 6 6 ee ee ee ee ee ee ee $170 
Moby Hyphenator II (185,000 words fully hyphenated/syllabified) . ©. 6 6 6 6 6 ee ee es $105 
Moby Words II (610,000 words & phrases with Scrabble(tm) word list, place names, baby names, acronyms, core list for spell checkers) $100 
U. S. Cities (names & longitude/latitude of 32,000 U.S. cities and 6,000 state boundary points). . ©. 2. / ee ee ee ee ee ees $35 
The World Digitized (100,000 longitude/latitude of world country boundaries) ©. © 6 ee ee ee es $30 
CD-ROMs 

BSD/386 are [X-compatible O/S; complete development package, full networking, kernel debugger, X11R5, DOS box; complete source code) $900 
AI CD-ROM (expert systems, neural networks, genetic algorithms, fuzzy logic, linguistics/natural language) . . . . - .- + - 2... 105 
FontMaster I Library (soft fonts for HP and HP compatible laser printers, 36 different type faces; 5,200 bit mapped fonts; 300MB) ... $70 
Prime Time for Unix (Volume 3, No. 1, January, 1994; over 6GB of Unix COOde) «sb 666 oe ELE CES EEE SOE @ Or $60 
Walnut Creek Libris Britannia (over 600MB of the best of British boards; not all source included) . . . 2. 1 6 ee ee eee ee ew $55 
Mailer’s Lookup (9-digit ZIP codes by street address or company name, distances between ZIP codes, phone locations; on-line tool) $50 


Linux/GNU/X gedrasil Computing (1st production release; run from the CD; TCP/IP & NFS; drivers; MPEG; SCSI support; lots more) aa 


Walnut Creek C User’s Group (Volumes 100 to 364) 2 6 6 6 we ee ee es 40 
Walnut Creek Linux V0.99.13 (100’s of tools; drivers for all sound, CDs, video; X-Windows; software engineering tools; easy install . . .. . $40 
InfoMagic Unix (three public domain Unix systems: 386BSD (version 0.1), Linux (version 0.99.10), and NetBSD) ........- +--+: $40 
InfoMagic Source Code (Berkeley Net/2, CH, GNU, Interviews, X, Andrew, XFree, Demacs & Winemacs, djgpp, Modula-3, etc.) ... $40 
Knowledge Media Multimedia (625MB & 13,000 files; 1,232 sounds, 179 books, 100 movies, 114 stacks, 606 programs, 214mods) ..... $35 
Walnut Creek Space & Astronomy (1000 images, 5000 text files, sci.space archive, astromony software; CD viewer included) ........ $35 
Project Gutenberg (literature, historical documents, reference books, census data, religious documents, math constants, etc.) ....... $35 
Knowledge Media Languages & Operating Systems (640MB of compilers, libraries, and operating systems; source code & executables) . . . $35 
Walnut Creek XIIRS and GNU 1R5 with contributed and comp.sources.x, over 120 GNU programs, complete Csource) ........ $35 
Walnut Creek Usenet and Simtel Unix-C (600MB) . 2. 6 6 1 ee ee $35 
Walnut Creek Giga Games (arcade, simulations, card games, education, trivai, cheat sheets; some SOUICE) s 66% 6 6 Hee ee He eS $35 
Austin Code Works Internet Warrior #1 (PC Internet tools: Gopher, Wais, Eudora, ph, reece Trumpet, TCP/IP, FAQs, drivers, docs) .. . $35 
NetGems of 1991 (comp.sources.*, alt.sources.* of 1991, plus X11R5 and GNUware and ; Unix file system not ISO-9660) ...... $20 
Walnut Creek Simtel 20 MSDOS Archive (C source code but lots of other stufftoo) . 2. 6 2 6 ee ee ee es $20 
Sprite Network Operating System (source code & documentation of Ousterhout’s Sprite O/S; Sun and DECStation boot images). ..... $20 
The Austin Code Works Voice: (512) 258-0785 
11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1342 
Austin, Texas 78750-3587 USA E-mail: info@acw.com 
Free surface shipping for cash in advance For delivery in Texas add 7% MasterCard/VISA 
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(continued from page 130) 

SS:ESP points to the Ring 0 stack load- 
ed from the TSS. Then, after loading the 
segment registers with the flat-model 
data selector, Ringolnit relocates _GATE- 
SEG in linear memory. 

Conventional VxDs never worry about 
their flat- model environment: Together, 
the compiler, linker, and LE loader take 
care of that. Without this luxury, RINGO 
faces two problems: 

First, GATESEG still resides in a DIS- 
CARDABLE memory block allocated by 
the Windows DLL loader, as specified 
in RINGO.DEF. Staying in there, RINGO 
would crash very soon, because there 
is no demand- paging for segments ref- 
erenced by selectors obtained at run 
time. Moreover, RINGO installs callback 
functions to be called in a context where 
page-swapping is out of the question. 
Eventually, RINGO would get hit when 
_GATESEG was swapped out, resulting 
in a page fault. If we assigned it a FIXED 
attribute, or Pagelocked it at run time, 
Windows would likely move _GATESEG 
in the linear address space somewhere 
below 640K, which is too expensive. Be- 
sides, the VMM (especially its debug 
version) and the debugger would get 
confused, since they expect VxDs to al- 
ways reside above the 2-gigabyte line. 

Second, the code and data references 
in RINGO aren’t properly resolved yet; 
they are still relative to the start of 
_GATESEG, as calculated by the as- 
sembler. 

The RelocateRingo function plays the 
part of the absent loader. First, it calls 
VMM’s _ PageAllocate service for a group 
of PageFixed (meaning also PageLocked) 
pages, large enough to accommodate 
_GATESEG. kelocateRingo simply moves 
the entire _GATESEG segment into this 
memory, whose linear address is above 
80000000h, exactly where VxDs should 
live. RINGO uses this address to resolve 
the code references. The movoffs macro 
in RINGO.INC (Listing Three, page 150) 
deals with this issue. Next, RelocateRingo 
creates a GDT data-selector alias for the 
_GATESEG run-time space to address 
its variables. This eliminates the need 
for resolving data references, because 
the offsets didn’t change when _GATE- 
SEG was relocated. The GS: segment 
overrides throughout the code explain 
how RINGO accesses the variables. 


Adding to the VxD Chain 

Let’s get back to Ringolnit. RINGO pro- 
cesses System_Control messages and 
needs a Device Descriptor Block (DDB) 
attached to the VxD chain. Since Win- 
dows 3.1 provides no VMM service to 
return the DDB root, RINGO gets it us- 
ing another piece of undocumented 
VMM functionality. 


The VMM contains an INT 20h dyna- 
mic linker for VMM and VxD function 
calls. To access a VMM or VxD service, 
VxDs use the VMMCall or VxDCall 
macro, which expands into 6 bytes: 
OCDh 20h CNT 20h) followed by a 
DWORD composed of the VxD ID and 
the service number. For example, _ A//o- 
cate_GDT Selector is service 76h pro- 
vided by VMM (VxD ID 1), so its 
DWORD is 010076h. When someone 


The functionality 
RINGO relies upon 
1s so central to 
Windows that it will 
likely remain in the 
future versions 





first issues a VMMCall or VxDCall, the 
interrupt gate assigned to INT 20h calls 
the centralized handler within the VMM. 
This handler saves all the registers, 
makes an indirect call to the dynalink 
handler, and the fun begins: 

The dynalink handler looks back at 
the stack, finds our six bytes, extracts 
the device ID and service number, and 
passes them to a helper function, which 
traverses the DDB linked list and returns 
the requested service address. In other 
words, this is just like a GetProcAddress 
for VMM and VxD calls. A side effect of 
the helper function call is that it returns 
the device DDB pointer in the ECX reg- 
ister. In the case of the VMM macro call, 
ECX contains a VMM DDB pointer, 
which is the device-chain root we’re 
looking for. The dynalink handler patch- 
es the original six bytes of the macro 
call, making them look like a 32-bit near 
calls to the device service, and returns 
back to the interrupt dispatcher, which 
restores the registers, including EIP. Our 
VxD executes again at the same address 
as the INT 20h, but this time using a di- 
rect service call instead. Neatly done! 

The DynalinkTrick function in CALL- 
GATE.ASM (see Listing Four) uses this 
knowledge to get the VxD root. Based 
on the fact the dynalink handler is one 
of the VMM faults, DynalinkTrick in- 
stalls its own handler, Ringo_Dyna- 
link_Handler, using the Hook_VMM_ 
Fault service. Effectively, this operation 
simply swaps function pointers in the 
fault call table. DynalinkTrick then 
makes a dummy call to the Get_VMM_ 
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Version service, giving Ringo_Dyna- 
link_Handler one chance to execute. 
The latter calls the original dynalink han- 
dler and saves the value of ECX. Finally, 
DynalinkTrick restores the original INT 
20h fault and exits with the VMM DDB 
pointer in hand. 

The VxD chain is a linked list, and 
RINGO inserts itself right after the VMM. 
You can run the VXDLIST program from 
the December 1993 “Undocumented Cor- 
ner” to verify this. The function Ringo- 
ControlProc installed as a Control Pro- 
cedure in the DDB responds to the VMM 
messages until we disconnect RINGO 
from the device chain. As Figure 1 shows, 
GATEVIEW displays these messages. 

Finally, Ringolnit creates a callgate 
for SeeYouAtkingO using undocumented 
_Allocate_GDT_Selector functionality de- 
scribed earlier and returns it back to Lib- 
Main in the form of a ready-to-use far 
pointer. 

To sum up, we wrote the flat-model 
code and integrated it with a Windows 
DLL using ordinary tools. After that bi- 
nary started, we set up the environment 
and programmatically launched our VxD 
to the VMM sphere of influence. Finally, 
we established the fast communication 
channel for user-mode programs to talk 
to our VxD. When the DLL usage count 
decrements to 0, and the WEP entry 
point gets called, RINGO discontinues 
his membership in the VxD club, de- 
allocates all its resources, including the 
callgates, and gracefully disappears. A 
small taste of plug-and-play! 


GATEVIEW 

What kind of goodies can RINGO get 
for us? Since it’s also a DLL, RINGO ex- 
ports five functions which are just shells 
around calls through the gate to SeeYou- 
AtRingO. GATEVIEW gets a lot of stuff 
from RINGO by calling these exports. 
As Figure 1 shows, it dumps the con- 
tents of the Page Directory and any Page 
Table, GDT, LDT, IDT, TSS, Control, and 
Debug registers, the list of running VMs 
and their parameters, and the list of in- 
stalled VxDs, including RINGO itself. 

Even if you don’t press any GATE- 
VIEW buttons, the lower list box will re- 
flect internal VMM events relevant to the 
VM rnultitasking. Every time one of these 
events occurs, the VMM sends a mes- 
sage to all VxDs. Since RINGO is a le- 
gitimate (though oddly created) VxD, it 
sees these messages and passes them 
on to GATEVIEW by calling PostMes- 
sage in a nested execution block. (See 
the full CALLGATE.ASM, available elec- 
tronically.) 

If you press GATEVIEW’s DOS but- 
ton, you won’t be able to start a DOS 
box until you press it again, because 
RINGO will return the carry flag set to 
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the Create_VM control message. If you 
press the button before starting Microsoft 
Visual C++, it refuses to compile any- 
thing, saying “Error initializing build 
VM.” This should convince you that Vi- 
sual C++ runs a hidden VM. 

What can be done with the technique 
presented here? As one example, con- 
sider hardware device-driver DLLs in- 
stalling Ring 0 interrupt handlers. They 
would eliminate the interrupt-latency 
problem faced by their Ring 3 counter- 
parts, which force developers to write 
VxDs in the first place. Another appli- 
cation for installable VxDs would be a 
generic loader, doing run-time reloca- 
tions and fixups. With this, it would be 
fairly straightforward to create VxDs in 


C or even C++. And whereas Microsoft's 
VXDLDR can only load special dynam- 
ic VxDs located in LE files, the RINGO 
approach described here can load VxDs 
residing in normal Windows DLLs. The 
only significant difference between 
RINGO and conventional VxDs is that 
RINGO doesn’t receive VMM initializa- 
tion messages. If your VxD doesn’t pro- 
cess these messages, there would seem 
to be several advantages to the RINGO 
approach. If you can think of other uses 
for installable VxDs, I'd welcome your 
suggestions and comments. 


DDJ 
(Listings begin on page 150.) 
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Epsilon Programmer's Editor combines a powerful and sophisticated ~ 
command set with hardware savvy that takes full advantage of your 
PC's display modes, memory options, and other features, all so you can 
be more productive. With mouse support, a convenient concurrent 
process buffer, fast C tagging, enormous file capacity, and much more, 


Epsilon makes even your most arduous programming tasks manage- 
able. So make tomorrow's coding easier-—order Epsilon today. 


Epsilon 6.5 costs $250, with a 60- 
day money-back guarantee. You can 
order Epsilon for DOS, 0S/2, SCO 
Unix, or Interactive Unix. 


We are committed to continually 


Expanded Screen Modes Ever try to edit a 30+ine 
function on a 25-line screen? With Epsilon, it’s no problem to see the 
whole function. On any standard VGA board, Epsilon can display 25, 
28, 35, 40, 43, or 50 lines on screen, and it’s easy to add any other 
modes your board supports. And, unlike some other editors, Epsilon 
doesn’t make you restart just to change modes—you can toggle 


between them with a simple keystroke. 


improving Epsilon. When you purchase 
Epsilon, you can rest assured that we 


will continue to enhance it to take 


Full xms and Ems Support Epsilon fully utilizes either Ems 
Or XMS memory, as well as upper memory blocks between 640kb and 


1 meg. Epsilon will use that space for the text you edit, as well as for 


advantage of advances in hardware 
and software technology. We have 
been doing just that since 1984. 
Call us now at (412) 421-5911. 


its commands, making it easy to edit even very large files. Why have 
all that memory and not use it? 


Advanced Emacs-style command set  fpsilon’s 
comprehensive programming environment will make you more produc 


tive, because its well-integrated, extensive command structure does more 


Lt SJ ar~u 
Lugaru Software, Ltd. 
5843 Forbes Avenue 
Pittsburgh, PA 15217 
(412) 421-5911 
(412) 421-6371 Fax 


in fewer keystrokes. For example, like some other editors, Epsilon can 
list files in a directory that match a pattern. But only Epsilon’s commands 
work everywhere in the editor, so you can use Epsilon’s sophisticated 
searching commands fo locate the only file among thousands with two 
adjacent digits in its name. It’s this kind of command integration that 
makes Epsilon the most powerful PC editor you can buy. 
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Come and see us at Software Development, booths 1837 - 1839. 


Available at Bookstores Everywhere A Division of MIS:Press 
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PROGRAMMER’S BOOKSHELF 


Legal Self-Help for 
Software Developers 


Jonathan Erickson 


ome of the thorniest problems pro- 

grammers end up wrestling with 

don’t involve advanced algorithms, 

new APIs, or obfuscated code. Far 
too often, the nastiest ones revolve 
around legal issues — copyrights, trade 
secrets, software patents, employment 
agreements, distribution contracts, and 
the like. In fact, in these days of intel- 
lectual- property confusion, the biggest 
difference between a one-person code 
shop and a multimillion- dollar corpora- 
tion seems to be the number of lawyers 
on retainer. The bottom line is that soft- 
ware developers— whether they’re in- 
dependent contractors writing software 
for retail or in-house programmers cre- 
ating proprietary code— need to have 
a basic understanding of their legal rights 
and responsibilities. 

In general, the programming and 
legal professions cross paths in two 
areas: individual rights and software 
protection. For example, when you go 
to work for a company as an em- 
ployee or contractor, you take along 
a certain body of knowledge — skills, 
algorithms, utilities, and so forth. If 
you write a program using one of your 
homegrown tools or techniques, do 
you give up rights to it? What’s the 
best approach to protecting your soft- 
ware: trade secrets, copyrights, patents, 
or onerous licensing agreements? Much 
to their attorney’s delight, many pro- 
grammers are using all of the above 
to protect individual pieces of soft- 
ware because it’s unclear exactly what 
is the best form of intellectual- property 
protection. 

When you get down to it, however, 
the law isn’t rocket science, no matter 
what lawyers would have you believe. 
While I wouldn’t advocate Mrs. Bob- 
bitt’s defending herself before an all- 
male jury, you can still educate your- 
self to the point where legal-babble is 
at least as understandable as Visual Ba- 
sic. Software Development: A Legal 
Guide and The Software Developer’s and 
Marketer's Legal Companion, both writ- 
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Stephen Fisbman : 
Nolo Press, 1993, 300 PP-, 844 95 
ISBN 0-87337-209-3 


Gene K. andy 
Addison-Wesley, 1993, 548 p pp. 
$34.95 

ISBN 0- 201-62276-9 


ten by lawyers experienced in software 
development and intellectual- property 
issues, do just this for software devel- 
opers. Predictably, the two books cov- 
er much of the same territory, and both 
provide electronic versions (on MS-DOS 
disks) of ready-to-use forms, agree- 
ments, letters, contracts, checklists, and 
similar boilerplates. 


Software Development: A Legal Guide 

Of the two books, Stephen Fishman’s 
Software Development: A Legal Guide 
generally goes into more depth, partic- 
ularly on volatile topics such as soft- 
ware patents. (The 60-page chapter on 
patents was actually written by patent 
attorney Leigh Hunt.) In addition to pro- 
viding a historical and legal background 
on software patents, the book also dis- 
cusses how to determine if your soft- 
ware is patentable, how to go about 
getting a patent, where to search for 
prior art (the locations and phone num- 
bers of dozens of nationwide patent- 
depository libraries are listed), and how 
to understand the patent-classification 
system (not as easy as you’d expect). 
The discussion of software patents was 
refreshingly honest, considering that it 
was written by an attorney— or maybe 
it’s just that I agree with the author 





“only the powerful (or 
very determined) can play the patent 


when he says, 


game.” Finally, the author discusses 
what you can do if you’re accused of 
patent infringement. 

To my mind, trade secrets have al- 
ways been a better way than patents 
to protect software. However, my un- 
derstanding of trade-secret law has 
been largely anecdotal. Fishman’s de- 
tailed analysis of the topic and his dis- 
cussion of the steps you take to iden- 
tify and protect secrets filled in the 
gaps for me, particularly when he com- 
pares trade secrets to both copyrights 
and patents. 

Interestingly, Software Development 
also has a timely chapter on multime- 
dia, a subject fraught with legal land 
mines. While Fishman’s focus is for the 
most part on how you obtain permis- 
sion to use copyrighted materials (text, 
photos, video, audio, and so on), he 
also examines public domain and the 
fair-use exception to copyrighted 
works. 

As for individual rights, Fishman de- 
votes specific chapters to employment 
agreements (from the perspective of 
both employer and employee), inde- 
pendent-contractor agreements, agree- 
ments to develop custom software, and 
ownership of software created by em- 
ployees and independent contractors. 
Particularly useful when dealing with 
the Internal Revenue Service are the 
guidelines Fishman provides for soft- 
ware companies that use independent 
contractors. 


The Software Developer's and 
Marketer's Legal Companion 
Fishman’s orientation in Software De- 
velopment: A Legal Guide is largely no- 
nonsense reference — just the facts, 
ma’am. Gene Landy’s Legal Compan- 
ion, on the other hand, is more read- 
able and loaded with anecdotes. 
(Landy’s chapter on trade secrets and 
confidentiality agreements starts off with 
the well-documented travails of Gene 
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Wang’s jump from Borland to Syman- 
tec.) That’s not to say that because Le- 
gal Companion is more entertaining, 
it’s less valuable: While Landy’s book 
overlaps with Fishman’s, Legal Com- 
panion delves into topics such as beta- 
test agreements and software liability 
that aren’t directly touched upon in 
Fishman’s book. 

It’s significant that the Legal Com- 
panion is written for software devel- 
opers and marketers. To this end, 
Landy also examines distribution and 
dealer agreements, shrink-wrap li- 
censes and warranties, and end-user 
agreements. Of special note is a chap- 
ter on international software distribu- 
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Four Great C Tools in 
One Coordinated Package 
¢ C-Xref for cross referencing 
¢ C-Tree for function call analysis 
¢ C-Lines for outlined listings 


¢ C-Format to reformat C programs 


Cross-Reference 
Usage symbols: 


a symbol, function, or macro is declared 
a function is declared by being used 


symbol's address is taken: &abc 


symbol takes on a new value: i=1; or i++; 


macro is undefined: #undef COUNT 


cos(double), returns double 
trigz.c 3# 10 


PI, macro: 3.14159265359 
trig.h 
trigl.c 
trig2.c 


sin(double), returns double 
trig.h 
trigl.c 
trige.c 


tion (including export controls), in 
which Landy discusses how European 
and Japanese intellectual-property laws 
differ from those in the U.S., as well 
as the ins and outs of setting up dis- 
tribution agreements with non-U.S. dis- 
tributors. 

Landy further provides guidelines for 
negotiating software- publishing agree- 
ments, including license and royalty 
issues, sublicensing, sales auditing, war- 
ranty and indemnification issues, and 
termination provisions. This is followed 
by a chapter on distribution channels 
(including shareware), pricing, war- 
ranties, franchise and antitrust laws, and 
related information. 


-Vision 


Eight Reasons to Choose C-Vision 
1. Built with 386 DOS extender 

technology for high speed and 
SO you won’t run out of space. 

. Intelligent cross-referencing — 
can distinguish between decla- 
rations, uses and modifications 
of variables 

. Intelligent labeling of trees and 
cross-references provides the 
types and prototypes of vari- 
ables and functions 

. Cross-reference information can 
be dumped to disk as ASCII 
files and manipulated directly 

. Uses the same syntax engine as 
the thoroughly tested PC-lint 

. Project file compatible with 
PC-lint 

. Numerous options for cus- 
tomization of output 

. “Stunningly bulletproof” 

Computer Language, Sept.-1992 


sR} at-bat oh ae ln aX 


: tan(double), returns double, trig2.c a 8 


sin_1(double), retur 
trigi.c 


tan(double), returns 
trig2.c 


[ei qu lfo lao: 
#include "trig.h" 


static double sin_1( double x ) 
{ 
double y; 

C if€ 27.0 -4* x * x == 27.0 ) 
{ return x; } 

y = sin_1( x/3.0 ); 
return y * (3 - 4 * y * y): 
B 


OONAUKRWND = 


double sin( double x ) 
{ 
C if( x <0 ) 


{ retiirn -csin(-x)\: 3 





: fo cost couble), returns double, trig2.c a 3 

: >—k>-—sin(double), returns double, trig1.c @ 12 [self] 

: r aes Se returns double, trig1.c a2 3 [self] 
>—k_>-PI, macro: 3.14159265359, trig.h @ 1 


Gimpoel Software 


3207 Hogarth Lane, Collegeville, PA 19426 


CALL TODAY (215) 584-4261 
Or FAX (215) 584-4266 


Only $139 
Specify MS-DOS or OS/2 
30 Day Money-back Guarantee. 


PA add 6% sales tax. 
C-Vision is a trademark of John Rex and Gimpel Software. 
PC-lint is a trademark of Gimpel Software. 


Boilerplates 

Between them, Software Development 
and Legal Companion also provide 
hardcopy and electronic versions of 
nearly 40 documents, ranging from 
nondisclosures and multimedia privacy 
releases to source-code escrow and 
shrink-wrap license agreements. In most 
cases, the forms are explained or an- 
notated so that you can use them with- 
out having to consult a lawyer. 


The law isn’t rocket 
sclence, no matter 
what lawyers would 
have you believe: 
You can still educate 
yourself to the point 
where legal-babble 
is at least as 
understandable as 
Visual Basic 





Copyright, patent, and other regis- 
tration procedures are also detailed; 
Legal Companion even has an official 
copyright- registration form bound into 
the book. 

Using just one of these boilerplate 
forms or letters will more than pay for 
the cost of the book. 


Conclusion 

Having to worry about legal issues can 
be a distraction to the actual program- 
ming process. However, in this day and 
age, writing software without consider- 
ing legal ramifications is akin to driving 
at night without lights you can’t see 
where you're going, and you can’t see 
what’s coming your way. 

Neither Fishman’s Software Develop- 
ment nor Landy’s Legal Companion will 
solve your problems once subpoenas 
are being served, but either of them may 
save you from getting that mired down 
in the first place. If nothing else, the two 
books make it possible for you to car- 
ry on a meaningful dialogue with a 
smooth-talking latter-day Perry Mason 
when (not if) you have to engage legal 
counsel. 


DDJ 


To vote for your favorite article, circle inquiry no. 14. 


Dr. Dobb’s Journal, March 1994 
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Guys Will be 


at X hibition...Will You? 


Need to start programming with 
those “sissy icons and windows”? 


Need Client Server applications 
and don’t feel like just using zeros? 


You need the 
Mhibition 94 
Technical 
Conferences 


e X Window System 
Development Conference 
User Interface Issues, 
Release 6, Motif 2.0, 
COSE’s CDE, Develop- 
ment Tips & Techniques, 
Cross Platform Issues, 
Futures 


Microsoft Windows NT 
Development Conference 
OS Programming, User 
Interface Issues, Win32, 


Objects, Client Server, 
Meee ae Networks & System 


Administration, Futures 
¢ Unified UNIX® Conference 
Spec 1170, COSE, Cross Platform, Client 
Server, Objects & CORBA, Distributed 
Computing, Networks & System Adminis- 
tration 





X Window System is a trademark of Massachusetts Institute of Technology, UNIX is a 


You need the 
MKhibition 94 
Tradeshow 
Exhibits 


Industry Exhibits 


Where leading vendors showcase X be l ice ] TT | Oo N =) 4 


new products and technologies 





e Application Theater Corporate Development Conference 
A theater on the show floor, where 
you can view live demos of new 
peoduce June 20 - 24 

¢ Industry Forum San Jose 
A free conference with “How to we ae 
Evaluate...” sessions, product and Ca é ifo reaica 


technology presentations, designed 
to increase your effectiveness asa 


buyer For more info: 
mail xhibit@Cics.com 
orcall 1.800.234.XHIB 


outside the U.S. call +1.617.621.0060 or fax +1.617.621.9555 


registered trademark of X/Open Company, Microsoft is a registered trademark and Windows NT and the Windows NT logo are trademarks of Microsoft Corporation. 
Xhibition is a trademark of Integrated Computer Solutions, Inc. 
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Call Cheryl Canion today at (415) 358-9500 to develop a customized advertising 
campaign tailored to your marketing needs. Turn the page for more products. 


We are proud to announce 
another fine game written with 


Fastgraph™ 


Pickle Wars by Karen Crowther. High Speed parallaxed scrolling with 
sprite animation, artwork by Les Pardew, and music by Bobby Prince. 
Fastgraph Programmer's Graphics Library 
Only $199 


Unlock the secrets of DOS graphics programming with the graphics 
library preferred by shareware and commercial games programmers. 


C ¢ C++ ¢ Pascal ¢ Basic ¢ Fortran 


Ted Gruber Software Voice +705) 735-1980 
P.O. Box 13408 FAX (702) 735-4603 


Las Vegas, NV 89112 BBS (702) 796-7134 


Visa/MC/COD Demos available No royalties 
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REAL-TIME CASE TOOLS 


Bayfront's Computer-Aided Protocol Engineering (CAPE) Tools: 
Captures the protocol or state machine design - Formalizes software state machine development 
Generates ANSI C Code targetable to any operating — - Examples include the ISDN 0.931 protocol 
system or hardware platform - Currently in use internationally creating complex 


Automatically draws state, state/event and CCITT real-time, communications and client/server systems 
SDL diagrams such as LAN Hubs, ATM and voice/data switches, 


Rapidly creates a working model of the protocol 


recy viConnect.Net) > q 
StantTimer(Tee 
recvi{ConnectUsr) -> 


CAPE Tools fat Windows $550, | Working ‘raul eno disk $45 


Bayfront Technologies Inc, 1280 Bison B9-231, Newport Beach, CA 92660 


For info: 714 436.0322 Fax. 714 436 1808 
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C preprocessor for fuzzy logic 


Integrated — seamlessly combine fuzzy logic 
reliability with C power 

Portable — use.with most ANSI G:compilers 

Extend C.= add membership functions, consequence 
functions and fuzzy logie control blocks to C 
Accessible — easily call fuzzy logic functions from C 


421 King St. N., Waterloo, Ont. N2J 4E4 
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ee protocol applications and VSAT equipment 








ielb tm & om Gxele (sie) sm Oy DE .<O)kY | 


CCITT Standards « RFC’S &IEN’S 
Pebeedens. Tools & Utilities 





info @infomagic.com 
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Time Arts Signature 
Graphics Class Library 


The object-oriented framework 
for all your future graphics 
development. 


65 800-959-0509 
707-576-7722 


Time Arts Fax: 576-7731 


1425 Corporate Center Parkway 
Santa Rosa, CA 95407-5434 
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Add SNMP Networking Protocols to your system design with: 
FUSION Developer's Kit 


e FUSION MIB 2 with Extensions 

eT] MIB, Ethernet Repeater MIB 

e Modular Design Eases Porting 

e Available in C source code 

e Full Support, Training & Consulting 


oogaie Pacific Softworks 
SS 
For More Information Call 
800-541-9508 or 805-484-2128 or Fax 805-484-3929 


Also Available Embedded TCP/IP & Windows Developer Kits 
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The Portable C-database System 


Available with CQL 


H SUPPORTS 4 


Supports Database, Royalty Free 
Memo, and Index UNIX SYS V, E 
formats of BSD, OS/2, Includes 


dBase Ill, dBase IV, Windows 3.X Shrouded Source 
Clipper & FoxBase and NT, a 


a DOS, Compatible with any 


Available with the Novell NLM. AKSI or a Complier 


COL Implementation 


of ANS! Level 2 SQL 

. ODBC, and with =e, 
Ciphering and library Documented 

Password Mechanisms interfaces. Source Available 


Machine Independent Software Corporation 
491-B Carlisle Drive Herndon, VA 22070 
703 435-0413 Fax: 437-8640 BBS: 437-8557 


APIS Software 
BolongarostraBe 113 D-65929 Frankfurt, Germany 
Country Code 49 Tel: [0]69 30 39 06 
Fax: [0169 31 75 31 
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EOS: Evolutionary Object System v1.1 


A C+ Genetic Algorithm Application Framework. 
The Natural Selection for Genetic Algorithm Applications 


Incorporate the power of Genetic Algorithms into your next C++ 

project. Genetic Algorithms are robust search and optimization 

procedures that mimic techniques used by nature. Genetic 
Igorithms are useful in Finance, Al, Optimization, Design, 
cheduling, Planning, etc. 


EOS contains over 80 classes that you combine to construct 
irtually any type of GA. You write the application specific portion of 
our problem and EOS does the rest. No knowledge of GA theory 

required. Extensive documentation and sample source are included 

or both MS Windows and DOS. Many new features in version 1.1. 

Experienced practitioners will find EOS easily extensible using C++ 

inheritance. Learn more about GA's by ordering our White Paper & 


he Financial GENE-ius Tool Kit is the first of several add-on tool 
kits for EDS. This tool kit allows a developer to build financial 
rading systems that combine the robust search methods of 

enetic Algorithms with the proven methodology of Technical 
Analysis to construct sophisticated trading systems. If you want to 

ash in on the application of genetic algorithms to commodities 
rading but are unsure how to begin, then this tool kit is for you. 

ontact us for more information on this and other GENE-ius tool 
kits. Introductory Price: $599 (requires EDS v1.1) 


Borland & MS C++ EOS Libs: $139 © EOS Source Code Lic: $599 
GA White Paper & EOS Demo Disk: $10 


Order Today: 516-249-4700 © VISA® MC ® Check 
Man Machine Interfaces, Inc. 
555 Broad Hollow Rd. Suite 230 Melville NY 11747 
516-249-4700 Fax: 516-420-4085 


EOS was formerly called EvolvE. 
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Client/Server, Transaction Processing 


Now your Windows Help 
can be your UNIX Help. 


HyperHelp™ 
Context Sensitive * Accepts Windows 3.1 
Help Files « Single Function API * 
PostScript Printer Support * Motif & 


Openlook « Accepts FrameMaker 
& SGML Files ¢ No Royalty! 


ristol Technology Inc. 


tel: (203) 438-6969 fax: (203) 438-5013 — email: info@bristol.com 


FTP a demo: ftp.uu.net in vendor/Bristol NA 
PURIFY’d 
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UU S-HUK 
bUUNH 
NU Whi 


Migrate to Windows 


without re-writing your 
entire DOS application 
in native Windows. 


WINGate lets DOS applications perform interprocess 
communication with other DOS and Windows programs. 


® Access and share Windows global memory objects. 
® Launch and terminate any DOS or Windows app. 
® Perform DDE Execute, Poke and Request Transactions. 
® Read/Write data to and from the Windows Clipboard. 
® Control any window's size, position, title, execution priority or status. 
® Send keystrokes, mouse movements and button events 
-to any application. 
® Create the transactions of your imagination with 
WINGatle 's 36 functions of API. 


Libraries available for all major languages. 


WINGate Developer’s Toolkit $295. 


(includes all C/C++ libraries) Additional libraries @ $49. 


WINGate Technologies, High Street Court. Suite 303 Morristown, NJ 07960 
800-WINGate (946-43283) 201-539-2727 
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Intelligent High Speed 
Communications 


GMM Sync4/CPP™ 

High Performance NEC™ V53 16MHz CPU 
80X86 Code Compatible 

4 Ports, Up to 4 Mbps Sync / Async 

Zilog™ 85C30, 85230 (SCC) 

512K Dual Ported Ram Up to 4 MB 

Evals to Developers!! 





Call or fax for full details! 
OEM and Dealer Inquires Welcome 


GMM Research 
18092 Sky Park South #E Irvine CA, 92714 


714/752-9447 Fax 714/752-7335 
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Automatically Translate Your Old Code Into Readable 
and Maintainable ANSI C with the latest 
PASCAL and BASIC to C Translators. 


Available For: Turbo Pascal, VAX Pascal/Basic,Microsoft 
Pascal/Basic 
For More Information Call Now! 


Technosoft (US): 815-397-3214 
Technosoft (Europe): +44-264-781626 
All Registered Trademarks Acknowledged 
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Graphics & Timing Tools 


BGI SVGA Video Driver Toolkit New Toolkit! 


Provides Super VGA driver support at up to 1280x1024x256 for most popular SVGA 
cards using the Borland BGI graphics library. Support for hics mode mouse 
and multiple video pages. Inport/export popular bitmap file formats. Supports 
Borland DOS language compilers in real and protected mode. $129.95 w/source. 


BGI Font Toolkit New Toolkit! 


Complete replacement for the graphics text functions in the Borland BGI se aia 
library. Corrects bugs in BGI text functions, allows arbitrary rotation, bolding, 
underlining, and Haliclesng of BGI fonts. ry eete additional bitmap font formats for 
filled font rendering. orks with any BGI video or allel? driver. Supports 
Borland DOS language compilers ir. real and protected mode. $89.95 w/source. 


BGI Printer Driver Toolkit New Version! 


Provides drivers for Boriand's BGI graphics library to ty eth a wide variety of 
poner plotters, and bitmap file formats. Support for EMS/XMS. Print popular 

itmap file formats. Extensive color device support. Not a screen dump - load our 
drivers with BGI's initgraph and get full output device resolution. Supports Borland 
DOS language compilers in real and protected mode. $129.95 w/source. 


BGI For Windows Port DOS BGI Code to Windows 


Gives you an interface to the Windows 3.x GDI compatible with Borland BGI 
graphics calls. Port your DOS BGI graphics code itadetaeaet to Windows. Full 
support for 256 color poet BGI stroke fonts, high resolution displays, and 
rasterized enone & BGI extensions supp TrueType and 24 bit color. Supports 
Borland Windows Ian 129.95 w/source. 


PC Timer Tools Event Timing and Scheduling 


Brings microsecond resolution timing to your DOS application with extensive 
functions for timers, delays, alarms, timer tick management, and thread 
scheduling. Ideal for execution profiling, data acquisition, and process control. 
Supports Borland DOS compilers, MSC/C++, Intel 386 CB, Zortech, $89.95 
wisource. PC Timer Objects for C++ and Turbo Pascal OOP - $89.95 w/source. 


All toolkits include The Official Fine Print 


complete source (in both C and Turbo Pascal), eee distribution 
license, and our 30 day "No Questions Asked" ie icy. d $5 = PERG USA, 
$10 elsewhere. VISA, MasterCard, and American Express accepted. Our toolkit 
code is found in a wide variety of commercial and private applications in daily use 


by over 100,000 end users. . 
Ryle Design 
Purveyors of Big Science since 1987 


PO Box 22, Mt. Pleasant, MI 48804 USA 
Voice/Fax: 517.773.0587 CIS: 73047,1765 


Demos and spec sheets available on our BBS: 517.772.2393 


guage compilers. 
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The only object oriented VCS for all platforms 
i) WINNER: Microsoft Systems Journal's competitive review 
WINNER: Computer Language’s Productivity Award 
/ ENDORSED BY: Intel, Oracle, Motorola, American Airlines... 
is: will: 
Project oriented version control Install in 10 minutes 
A “FileManager” for your source code Save you a minimum of 5 hours a week 


Cross-platform: DOS, WIN, 0/2, NT, UNIX, MAC... Track entire programs and projects 
Incredibly easy to use at 1/2 PVCS’ price NEVER lose a file 


CALL NOW for a risk-free look at and register 
to win | of 10 Microsolutions Backpack CD-ROM players ($500 value). 
Limited to first 1000. 
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EditMaster™ 


The yitimate BRIEF® gad! 

\ “ GREP (Multi-buffer and Multi-file search) 
\\ Y Multiple keystroke macros / 
» | Y Multiple scrap buffers vd more ; 
4 Y/Y Templates with autofill 

Y Enhanced search and translate 

Y Find next or previous function 


Y Brace/parentheses matcher 


Software 


& MR ER 


$89 95 


includes 
SOURCE! 


Y 50-Page user’s manual 


Order Line: 1-800-453-5277 


10210 W. 26th Ave. Suite 7 ¢ Lakewood, CO 80215 
~ Tel: 303.274.8088 @ Fax: 303.274.8279 


CIRCLE NO. 1225 ON READER SERVICE CARD 


We'll Tell You Just Once. 
Create Programs 10 Times Faster 
with Allegro CL\PC. 


Far more powerful than C++ 
or Smalltalk, Allegro CL\PC is truly 
amazing. It offers you incremental 
compilation, memory management 
and a Standardized library of over 
700 functions and classes. Plus a 
built-in editor, debugger, browser 
and profiler. 


Closely model the real world. 
Featuring CLOS, the Common Lisp 
Object System for advanced object- 


oriented programming, Allegro (Gall now and order 


CL\PC makes it easy to express 
difficult ideas. CLOS includes Allegro CL\PC 


multiple inheritance, dynamic for only $595 


redefinition and a meta-object —g $40() savings! 
protocol for added extensibility. 


Windows developers will love 
this development environment. 
You'll appreciate the native 32-bit 
compiler, access to the Windows 
API, and DLL support. Applications 
are portable to Unix workstations, 
and can be delivered royalty-free! 


OFFER EXPIRES MAY 31, 1994. 


ERANZ INC, 


FAX: (510) 548-8253 


TIT SRELE SIT ee: 
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ALGORITHM ALLEY 


Listing One (Text begins on page 127.) 


'xk*k BASIC Adaptive Block Coded (ABC) Image Compression 

‘ee (c)1993, E.F.Deel, CIS 72627,3026 

'*&*k PCX2ABC.BAS - Compression Demo Module, displays PCX to simulate video 
‘kkk camera output, captures image from screen, compresses & stores. 

'*kk Link with compression module, COMP.BAS 

'k**k NOTE: VGA is required and assumed 


DEFINT A-Z 


'--- Include declarations for compression module 
'SINCLUDE: 'COMP.DCL' 


'--- BASIC DOS/BIOS Interrupt routine 
DECLARE SUB InterruptX (IntNumber, Registers AS ANY) 


'--- External assembler components from Graphics WorkShop by 
y Crescent Software, used to display PCX and work with palette 
DECLARE SUB SetPaletteEGA (BYVAL PalReg%, BYVAL Value%) 
DECLARE SUB SetPalTripleVGA (BYVAL PalReg%, BYVAL Red%, BYVAL Green%, 
BYVAL Blue%) 
DECLARE SUB DispPCXVE (BYVAL Display%) 
DECLARE FUNCTION OpenPCXFile% (Filename$, Header$) 


'--- BASIC sub-program to handle palette and display PCX 
DECLARE SUB ShowPCX (Filein$, XSize, YSize) 


'--- Share compression statistics among modules (optional) 
COMMON noc, hre, vre, pec, zle, zrc, vile, bet& pet&, plt&, GPDat%() 


TYPE RegType 
AX 


S INTEGER 
BX AS INTEGER 
CX AS INTEGER 
DX AS INTEGER 
BP AS INTEGER 
SI AS INTEGER 
DI AS INTEGER 
FL AS INTEGER 
DS AS INTEGER 
ES AS INTEGER 
5S AS INTEGER 
SP AS INTEGER 


BusyFlag AS INTEGER 
Address AS INTEGER 
Segment AS INTEGER 
ProcAdr AS INTEGER 
ProcSeg AS INTEGER 
IntNum AS INTEGER 


END TYPE 


Save your lost profits with SecuriKey 
— a unique hardware device that 
prevents unauthorized use and 
duplication of computer software. 


e IBM, compatible & Macintosh 
Allows unlimited backup copies 
Can record software usage Systeme, inc. 
Available in custom colors & logos | 150 Wright Brothers 


Variety of programmable options Dr., Suite 560 


Salt Lake City, 
UNIX/XENIX Utah 84116 


FAX (801) 575-6621 
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DIM SHARED Registers AS RegType 


Filein$ = COMMANDS 

IF LEN(Filein$) = @ THEN 
CLS 
PRINT "SYNTAX: PCX2ABC Filename.PCX [-]" 
PRINT " - = Use lossy preprocessor" 
PRINT " Output written to Filename. ABC" 
END 1 

END IF 

x = INSTR(Filein$, "-") 

IF x THEN 
Lossy = -1 
Filein$ = LEFT$(Filein$, x - 1) 

END IF 

FileOut$ = Fileins 

x = INSTR(FileOut$, ".") 

IF x THEN FileOut$ = LEFTS(FileOut$, x - 1) 

FileOut$ = FileOut$ + ".ABC" 


CALL ShowPCX(Filein$, XSize, YSize) 
CALL Compress(@, @, XSize, YSize, Lossy, rsize&, csize&) 


IF csize& < @ THEN 
Registers.AX = &H3 
CALL InterruptX(&H10, Registers) 
PRINT "ERROR! Out of memory." 
END 1 

END IF 


‘switch to text mode 


CALL SaveABC(FileOut$, XSize, YSize) 


Registers.AX = &H3 
CALL InterruptX(&H10, Registers) 


‘switch to text mode 


'--- Print compression statistics 


PRINT "Raw image size 
PRINT "Compressed image 


"; reize&; "bytes ("; XSize; "X "; YSize; "pixels)" 


"; esize&; "bytes" 


ou i 


PRINT "Compression Ratio = @."; csize& * 100 \ rsize& 
PRINT 

PRINT "Pattern #Blks" 

PRINT i a es a ew ies oie " 

PRINT "None ="; noc 

PRINT "Horiz. Run = "; hre 

PRINT "Vert. Run ="; vre 

PRINT "Prime Color = "; pec 

PRINT "Zigzag Left ="; zlc 

PRINT "ZigZag Right = "; zrc 

PRINT "Vari. Length = "; vlc 

PRINT 

END @ lanai lena End Program <<<-<=<<-<- 


SUB ShowPCX (Filein$, XSize, YSize) 


Hdr$ = SPACES (68 + 768) 

IF NOT OpenPCXFile(Filein$, Hdr$) THEN 
PRINT "File Not Found" 
END 1 


CVI(MIDS (Hdr$, 5, 2)) 

CVI(MID$(Hdr$, 7, 2)) 

CVI(MIDS(Hdr$, 9, 2)) 

CVI(MIDS(Hdr$, 11, 2)) 

XSize = XMax - XMin + 1 

YSize = YMax - YMin + 1 

NumPlanes = ASC(MIDS(Hdr$, 66, 1)) 

PixelBits = ASC(MIDS(Hdr$, 4, 1)) 

IF (NumPlanes < 2) OR (PixelBits = 2) OR (PixelBits = 8) THEN 
PRINT "PCX must be 640x48@x16" 
END 1 

END IF 


BEE 
ta 
tou wou 


Registers.AX = &H12 
CALL InterruptX(&H10, Registers) 


"Switch to graphics 


i= 17 
FOR k = @ TO 15 
CALL SetPaletteEGA(k, k) 
t$ = MIDS(Hdr$, i, 1) 
r = ASC(t$) \ 4 
i=iti 
t$ = MIDS(Hdr$, i, 1) 
g = ASC(t$) \ 4 
i=z=ittl 
t$ = MIDS(Hdr$, i, 1) 
b = ASCc(t$) \ 4 
i=iti 
CALL SetPalTripleVGA(k, r, g, b) 
NEXT 
CALL DispPCXVE(@) 
END SUB 
e e 
Listing Two 


'x** BASIC Adaptive Block Coded (ABC) Image Compression 
‘eek (¢)1993, E.F.Deel, CIS 72627,3026 

'*k* SHOWABC.BAS - Demo De-Compression Module, re-displays 
'*k& compressed images from disk. 

'*k* Link with de-compression module, DECOMP.BAS 

DEFINT A-Z 

DECLARE SUB InterruptX (IntNumber, Registers AS ANY) 


"SINCLUDE: 'DECOMP.DCL' 
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TYPE RegType | Listing Three 
AX 


AS INTEGER 
BX AS INTEGER 'x*k* ABC Compression Module Declarations 
CX AS INTEGER 
DX AS INTEGER '--- External components from Graphics WorkShop by Crescent Software 
BP AS INTEGER DECLARE SUB GMove4VE (BYVAL FromCol%, BYVAL FromLine%, BYVAL Cols%, 
SI AS INTEGER BYVAL Lines%, BYVAL DestSegment%, BYVAL Direction%) 
DI AS INTEGER DECLARE SUB LineBF2VE (BYVAL x1%, BYVAL y1%, BYVAL x2%, BYVAL y2%, 
FL AS INTEGER BYVAL LineColor%) 
DS AS INTEGER DECLARE SUB GetPalTripleVGA (BYVAL PalReg%, Red%, Green%, Blue%) 
ES AS INTEGER 
SS AS INTEGER '--- BASIC Compression/Decompression SubRoutines 
SP AS INTEGER DECLARE SUB Compress (BYVAL X%, BYVAL Y%, BYVAL XSize%, BYVAL YSize%, 
BusyFlag AS INTEGER BYVAL Lossy%, rsize&, csize&) 
Address AS INTEGER DECLARE SUB ShrinkArray (BYVAL Segment%, BYVAL Addr%, nobytes&, noblks%) 
Segment AS INTEGER 
ProcAdr AS INTEGER '--- BASIC File Output Routine 
ProcSeg AS INTEGER DECLARE SUB SaveABC(Filename$, XSize, YSize) 
IntNum AS INTEGER 
END TYPE '--- Internal BASIC Block File Read/Write Routines 
DECLARE SUB BlkGet ALIAS "BSGET3" (BYVAL FileNum%, BYVAL Segment%, 
DIM Registers AS RegType BYVAL Addr%, BYVAL Bytes%) 
DECLARE SUB BlkPut ALIAS "BSPUT3" (BYVAL FileNum%, BYVAL Segment%, 
FileIn$ = COMMANDS BYVAL Addr%, BYVAL Bytes%) 
IF LEN(FileIn$) = @ THEN 
CLS ‘ke 
PRINT "SYNTAX: ShowABC Filename" Listing Four 
END 1 
END IF 'xk*k ABC De-Compression Module Declarations 
Registers.AX = &H12 ‘Switch to graphics '--- External assembler "components" from Graphics WorkShop 
CALL InterruptX(&H10, Registers) DECLARE SUB GMove4VE (BYVAL FromCol%, BYVAL FromLine%, BYVAL Cols%, 
BYVAL Lines%, BYVAL DestSegment%, BYVAL Direction%) 
CALL DeCompress(FileIn$, %, @, OK) 'Decompress & display file DECLARE SUB SetPaletteEGA (BYVAL PalReg%, BYVAL Value%) 
DECLARE SUB SetPalTripleVGA (BYVAL PalReg%, BYVAL Red%, BYVAL Green%, 
IF OK THEN BYVAL Blue%) 
DO: LOOP UNTIL LEN(INKEYS) ‘wait for keypress '--- External assembler component by Doug Herr 
Registers.AX = &H3 ‘switch to text ; Displays pixel block taken from a BASIC integer array 
CALL InterruptX(&H10, Registers) DECLARE SUB PutI(BYVAL segment%, BYVAL Addr%, BYVAL x%, BYVAL y%, 
END . BYVAL wide%, BYVAL high%) 
ELSE '--- Internal BASIC Block File Access Routines 
Registers.AX = &H3 ‘switch to text DECLARE SUB BlkGet ALIAS "BSGET3" (BYVAL Filenum%, BYVAL Segment%, 
CALL InterruptX(&H10, Registers) BYVAL Addr%, BYVAL Bytes%) 
PRINT "ERROR! Invalid file/file not found." DECLARE SUB BlkPut ALIAS "BSPUT3" (BYVAL Filenum%, BYVAL Segment%, 
END 1 BYVAL Addr%, BYVAL Bytes%) 
END IF '--- BASIC Compression/Decompression Routines 
DECLARE SUB DeCompress (FileIn$, BYVAL X%, BYVAL Y%, OK%) 
END DECLARE SUB ExpandArray (BYVAL inseg%, BYVAL inptr%, bytesz&, NoB1k%) 


End Listings 


ADDITHEIPOWEROFGRAPHICS TO YOUR PROGRAMS WITH GENUS 


Supporting the myriad of graphics adapters and printer devices available can be 
a real nightmare, and getting different toolkits from different companies to work 
together in your program is a big hassle. But not anymore! 


Genus offers a one-stop solution to your programming needs with its complete line of 
programming toolkits. Designed to work separately or work together, the GX 
Development Series allows you to incorporate graphics into your programs quickly 
and easily, saving you time and money. Not only are the toolkits easy to use, they are 
written in 100% assembly language for the smallest size and fastest code possible. 


Find out what thousands of professional programmers already know. . . 
For comprehensive graphics support, you need the GX Development Series! 





GX GRAPHICS is a complete graphics [7 ‘| GX IMAGES allows you to import and 
library supporting all graphics primitives &“\jexport bitmapped graphics in a wide 
from Pixels to Ellipses. ........ onty $249 variety of file formats. Available for DOS 


3») PCX TOOLKIT allows you to create, dis- CL — 
' play, and manipulate PCX images from PROTEUS allows you to create demos, 
almost any program. Available for DOS ‘a tutorials, and prototypes quickly and 

or WINdOWS. omy $249 CAS, ee ett omy $349 


én \GIF TOOLKIT allows you to create, dis- DEVELOPER’S PAK allows you to save 
“s play, and manipulate GIF images from 20% when you order 3 or more Genus 
almost any program............ ony $249 COOKIES. |... ae CALL FOR DETAILS 


[a7 | GX EFFECTS lets you add special effects, 
’ Xanimation, and sound to your pro- 
grams. Available for DOS or Windows. 
eee. onty $199 


| Lf GX TEXT lets you display bitmapped text 
: ¥/ and stroked fonts in any graphics mode 

, oo AA as simply as text mode and includes 
1155 DARY ASHFORD © SUITE 200 © HOUSTON, TX 77079 ¢ (713) 870-0737 600+ fonts... ony $149 



















ROPROGRAWN MIN 


GEWOS 









oun he ui wh calle (713) 870-0001 KX PRINTER provides comprehensive . Real ee a 
nce A Eee CONIC. t<@ craphics printer support for your pro- | "Versions Avail a 





grams (over 300 printers supported). 


e From Genus....6) 
| onty $349 e From Genus...) 


* Also Available GaMI 
©1993 GENUS MICROPROGRAMMING, NC. 5089 
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UNDOCUMENTED CORNER 


Listing One (Text begins on page 133.) 


/* CALLGATE.H */ 
typedef DWORD (FAR PASCAL *GATEPROC) (WORD svc, WORD cnt, DWORD extra) ; 


/* SeeYouAtRing® services */ 
#define Get386_Svc @ 
#define PhysToLin_Svc Get386_Sve + 1 //map phys to linear 
#define Register_Hwnd_Svc PhysToLin_Sve + 1 //register HWND 
#define Unregister_Hwnd_Svc Register_Hwnd_Sve + 1 //unregister HWND 
#define StopVM_Svc Unregister_Hwnd_Sve + 1 //toggle DOS box exec 
#define RemapGate_Svc StopVM_Sve + 1 //remap call gate 


//get system info 


typedef struct { /* call gate procedure parameters */ 


DWORD G_Dword; // Dword parameter 

WORD G_Word; // Word parameter 

WORD G_Sve; // service number 
}GPARAM ; 


/* RingoInit functions */ 
#define EXITRINGO OxFFFF 
#define INITRINGO @ 


Listing Two 


/* RINGO.C -- excerpts */ 
//#define CALLGATE_386 //define CALLGATE_386 to get gates from CALLGATE.386 


#include <windows.h> 
#include "386.h" 
f#include "callgate.h" 


#ifdef CALLGATE_386 

GATEPROC GetFirstCallGateVxD (FARPROC entrypoint,BYTE paramcount) ; 
void DestroyInitGateVxD (WORD callgateselector) ; 

#endif 


VOID WINAPI RingoInit (void) ; 

VOID WINAPI SeeYouAtRing@ (void) ; 

VOID WINAPI MakeSureOurSegIsInMemory (void) ; 

GATEPROC GetLdtRing@CallGate (FARPROC entrypoint, 
BYTE paramcount,WORD callgate) ; 

GATEPROC GDT_Gate,LDT_Gate; 


int FAR PASCAL LibMain ( HANDLE hInstance, WORD wDataSeg, 
WORD cbHeapSize, LPSTR lpszCmdLine ) 
{ 


FARPROC ri = (FARPROC) RingoInit; 


if (!(GetWinFlags () & WF_ENHANCED)) /*VxDs exist in enhanced mode only*/ 
return @; 


#ifdef CALLGATE_386 // get the GDT call gate from CALLGATE.386 
if (!(LDT_Gate = GetFirstCallGateVxD (ri, sizeof(GPARAM) /4) )) 
#else // get the LDT call gate with INT 2F, AX=168A 
if (!(LDT_Gate = GetLdtRing@CallGate (ri, sizeof(GPARAM)/4, @))) 
#endif 
return 9; 


/*** get the main call gate in GDT ***/ 
GDT_Gate = (GATEPROC)LDT_Gate (INITRINGO, sizeof (GPARAM) /4, 
(DWORD) SeeYouAtRing®@) ; 
if (cbHeapSize) 
UnlockData (@); 

return (1); 
} 
char vendor[] = "MS-DOS"; // Microsoft's signature 
GATEPROC GetLdtRing@CallGate (FARPROC gproc, BYTE params,WORD gatesel) 
{ 
#define VENDOR_SPECIFIC_API @x168a 
WORD ldt_map; // LDT selector, which maps LDT itself 
WORD (far * entryp) (void); // entry point to get the above 
LPCALLGATEDESCRPT CGateDescriptor; // build call gate descriptor with this 
WORD RW_ldt_map; /* ldt map selector fixes segment read-only problem */ 
WORD CGateSelector; / to be a call gate selector 
DWORD initgate_flat; // callgate procedure's linear address 


_asm { 

mov si, offset vendor 

mov ax, VENDOR_SPECIFIC_API 

int 2fh 

or al, al 

jnz no_vendor 

mov word ptr [entryp], di /* private entry point */ 
mov word ptr [entryp+2], es 

mov ax, 10h /* magic number */ 

} 


ldt_map = entryp(); /* returns LDT map selector */ 
_asm jne vendor_ok 

no_vendor: 
return 9; 


vendor_ok: 
// When run under SoftICE/W LDT alias returns read_only, give us a good one 
if (!(RW_ldt_map = AllocSelector (SELECTOROF((void FAR *)&GDT_Gate) ))) 
return @Q; 
SetSelectorBase(RW_ldt_map, GetSelectorBase(ldt_map)) ; 
SetSelectorLimit (RW_ldt_map, GetSelectorLimit (1dt_map) ) ; 
if ((CGateSelector = gatesel) == // we might already have one 
if (!(CGateSelector = AllocSelector(@))) // Get a selector for the gate 
{ 
FreeSelector (RW_ldt_map) ; 
return @; 


} 


// create a pointer to write into the LDT 


150 


CGateDescriptor = MAKELP(RW_ldt_map,CGateSelector & SELECTOR_MASK) ; 


// build 32-bit ring 3-to-@ call gate 
#define MK_LIN(x) (GetSelectorBase(SELECTOROF(x)) + (DWORD) OFFSETOF (x) ) 
initgate_flat = MK_LIN(gproc) ; 
CGateDescriptor->Offset_0_15 = LOWORD (initgate_flat) ; 
CGateDescriptor->Offset_16_31 = HIWORD (initgate_flat) ; 
CGateDescriptor->Selector = 0x28; // ring® flat code seg 
CGateDescriptor->DWord_Count = params & CALLGATE_DDCOUNT_MASK; 
CGateDescriptor->Access_Rights = GATE32_RING3; //pres,sys,dpl3,32CallGate 
FreeSelector (RW_ldt_map) ; // don't need you any more 
return ((GATEPROC)MAKELP (CGateSelector,@)) ; 

} 


DWORD WINAPI _export MapPhysToLinear (DWORD physaddr, WORD mapsize) 
i 
return (GDT_Gate) (PhysToLin_Svc,mapsize,physaddr); /* DPMI alternative */ 


} 
® e 
Listing Three 
;;3; RINGO.INC -- excerpts 
GPARAM struc ; parameters 
G_Dword dd ? 
G_Word dw 2 
G_Sve dw ? 
GPARAM ends 
CALLGATE_FRAME struc ; stack frame at the time of ring transition 
CG_pushbp dd ? 
CG_O1d_EIP dd 2 ; this is where we came from 
CG_O1d_CS dd t ; and will get back 
CG_Params db (type GPARAM) dup (?) ; call gate parameters 
CG_O1d_ESP dd 2 ; caller's 
CG_O1d_SS dd 2 ; stack 


CALLGATE_FRAME ends 


BuildGateStackFrame macro dataseg 
push ebp 
mov ebp,esp 
push gs 
push ds 
push es 
push fs 
push esi 
push edi 
ifidni <dataseg>,<_DATA> 
mov ax,ds 
mov gS,ax ; we'll access our data seg via gs 
endif 
mov ax,ss 
mov ds,ax ; ring @ flat data delector 
mov es,ax 
mov fs,ax 


ifdifi <dataseg>,<_DATA> 
call GetRingoGdtDataSel 


endif 
endm 
ClearGateStackFrame macro cleanup 

pop edi 

pop esi 

pop fs 

pop es 

pop ds 

pop gs 

pop ebp 

ret cleanup 
endm 


movoffs macro’ reg,off32 
mov reg, offset &off32 
add reg,gs: [ringo_flat] 


; run-time fixup 


endm 
Listing Four 


;;3; CALLGATE.ASM -- excerpts 


.386p 

include vmm.inc 

include ringo.inc 

include 386.inc 
public RingoInit,SeeYouAtRing@,MakeSureOurSegIsInMemory 
-GATESEG segment dword use32 public 'CODE' 

assume cs:_GATESEG,gs:_DATA 


RingoInit proc far 
BuildGateStackFrame _DATA 
cmp [ebp] .CG_Params.G_Svc , EXITRINGOCALL 
jnz short @f 
call RingoExit ; deallocate everything we've got 
jmp short retini 
@@: call RelocateRingo ; run-time relocation and fixups 
je short init_ret 
call DynalinkTrick ; get the VxD chain root 
call InsertRingoDDB ; welcome to the VxD club 
call CreateRingoGDTGate ; GDT call gate to SeeYouAtRing@ 
retini: mov edx, eax ; prepare return values for the ring 3 
shr edx, 16 
ClearGateStackFrame <size CG_Params> ; clear both ring stack frames 
RingoInit endp 
SeeYouAtRing® proc far ; The callgate service proc 
BuildGateStackFrame 


VMMCall Get_Cur_VM_Handle 
movzx eax, [ebp].CG_Params.G_Sve 


; always helpful 
; service dispatcher 


cmp eax, LASTSVC 
ja @f 
call gs:Gate_Service_Table [eax*4] 
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@@: mov edx, eax 
shr edx, 16 
ClearGateStackFrame <size CG_Params> 
SeeYouAtRing®  endp 
CreateRingoGDTGate proc 
movzx edx, word ptr [ebp].CG_Params.G_Dword ; offset16 
add edx,gs: [ringo_flat] ; fixup 
mov ax, cs ; VMM code selector 
mov ex, [ebp] .CG_Params.G_Word ; parameter count 
and cx, CALLGATE_DDCOUNT_MASK ; make sure it's a reasonable number 
or cx, GATE32_RING3 ; call gate type 
call BuildCallGateDWords 
VMMCall _Allocate_GDT_Selector,<edx,eax,2Q@@0@GGh> ; undocumented flag 
ror eax,16 
ret 
CreateRingoGDTGate endp 
BeginProc DestroyGDTCallGate, public 
movzx eax, [ebp] .CG_Params.G_Word 
VMMCall _Free_GDT_Selector,<eax,@> 
ret 
EndProc DestroyGDTCallGate 
BuildCallGateDWords proc 
movzX eax, ax 
shl eax, 16 ; selector 
mov ax, dx ; offset 9-15 
mov dx, ¢x ; offset 16-31 + type + count 
ret 
BuildCallGateDWords endp 


BIDET cE e Sere c Pe rer eS Cee Ler errr rer err err er ere ere rere rrr rr ere Eee e ree ee fe tt 
; To get the VxD Base (VMM DDB ptr) we're using the undocumented fact that 
; VMM's dynalink handler (considered a 'fault' 2@h in DDK spec parlance) 


; returns it in 


ecx. The idea is to hook VMM fault 2@h, call any VMM service 


; to get our fault handler receive control, call VMM's dynalink directly, 

; store ecx in a static variable, and hook fault 20h again, this time 

; with fault handlers reversed. 

EE CSCO GO iO SEAGRASS IOI AG AGC AGI IOI Ra CAC A I I a 11 1 21 8 21 21 8 


BeginProc 
mov 
twice: mov 
VMMCal11 
mov 
VMMCal1 
cmp 
jnz 
mov 
ret 
EndProc 


DynalinkTrick 

esi, gs: [OurDynalinkHandler] 

eax, 20h 

Hook_VMM_Fault ; install our handler 

gs: [OLD_DYNALINK_HANDLER], esi 

Get_VMM_Version ; need one call get it executed 
esi, gs: [OurDynalinkHandler] 

twice 

eax, gs: [VXD_FIRST] 


DynalinkTrick 
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Ringo_Dynalink_Handler proc 
call gs: [OLD_DYNALINK_HANDLER] 
Mov gs: [VXD_FIRST], ecx ; DDB pointer 
ret 

Ringo_Dynalink_Handler endp 


PhysToLin proc ; physical to linear address mapping 
movzx ecx, [ebp].CG_Params.G_Word 
VMMcall _MapPhysToLinear,<[ebp] .CG_Params.G_Dword,ecx,@> 


ret 
PhysToLin endp 
ringo_flat dd @ ; run-time space base 
OLD_DYNALINK_HANDLER dd iM) 
VXD_FIRST dd @ ; VxD chain root 
OurDynalinkHandler dd offset Ringo_Dynalink_Handler 
Ringo_DDB VxD_Desc_Block <,,,1,0,,'Ringo ',,offset RingoControlProc,,,,,,, > 
Gate_Service_Table label dword 

dd offset Get386 

dd offset PhysToLin 

dd offset RegisterHWND 

dd offset UnregisterHWND 

dd offset StopVM 

dd offset RemapCallGate 
_GATESEG ends 
end 


End Listings 





















TLIB Version Control 
For DOS, OS/2 and Windows-NT 


e The experts loved TLIB 4: 
“amazingly fast... TLIB is a great system.” PC Tech Journal 


“TLIB has features and power to spare... TLIB is easy to use and 
the fastest of the reviewed packages.’ Computer Language 


“T will not program without it.” Uptime Magazine 





e Now TLIB 5.0 adds: 


Automatic branching. Automatic version labeling across branches. 
User defined promote structures, for staged development. Exclusive 
whole-level change migration for customized software. N-way-tree 
version numbers. Branch and full locking. OS/2 & NT support. 





e Plus the features they loved in TLIB 4: 


Check-in/out locking. Branching, for parallel development. Keywords. 
Full binary file support (does not depend upon CRs in the file like other 
products). Wildcard and list-of-file support; can create lists by scanning 
source code for includes. Can merge (reconcile) multiple simultaneous 
changes and undo intermediate revisions. Network and WORM optical 
disk support. Mainframe-compatible delta generator for Pansophic, 
ADR, IBM, Sperry formats. Includes integrated PD MAKE by L. Dyer; 
also integrates with Opus™ MAKE, Slick™ MAKE, others. 







MS-DOS $139, OS/2 & NT (with MS-DOS) $195 + shipping. 
5 station network: MS-DOS $419, OS/2 $595. Call for other sizes. 


PO Box 4156, Cary, NC 27519 (919) 233-8128 
FAX: 233-0716 
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Star Sapphire Common LISP— 
Common LISP with Class 


An affordable, full-featured Common LISP for DOS. Not a toy! Only - we 4 MetaWiINDo 


$99.95. Supports 8Mb extended/virtual memory. Includes EMACS, 1Mb weal to cia miias nc ss 


Hypertext Help, and the 7 Find out why hundreds of leading applications from Autodesk, Hewlett-Packard, 
Common LISP Object IBM, Symantec/Peter Norton, SCO (the list goes on) have compared the field and 
system (CLOS). Order from : chosen MetaWINDOW the best graphics toolkit available. Top-rated performance in 
the Programmers’ Shop (1- YA , y, over 250 functions. Text and printer support built-in. Versions for DOS, plus 286 
800-421-8006). Site , and 386 protected-mode. Source code available, plus all products are Royalty-Free! 


eee Pricing - | MetACCEL-DOS/286/386 - Advanced support for hardware accelerated SVGA’s. 
all Sapiens software. fo Boosts graphics drawing speed 5-12 times over standard SuperVGA modes! wen! 


Sapiens Software oe FontWINDOW/Plus - Includes over 250 fonts, font editor, plus font builder and 
P.O. Box 3365 ” - importer utilities for creating fonts of any size from PostScript or True Type typefaces. 


ea Cruz, CA 95063-3365 METAGRAPHICS SOFTWARE CORPORATION 
269 Mount Hermon Road # PO Box 66779 =® Scotts Valley, CA 95066 
(408) 458-1990 fax: (408) 425-0905 Phone 408-438-1550 = Fax 408-438-5379 = BBS 408-438-5368 
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VB=mc?: Visual Basic Standards 
and Practices 


When the lights go down and the stars 
come out, Visual Basic transforms itself 
into a quantum event processor. J.D. 
Evans, Jr. (a.k.a., Dr. Focus) shows you 
the Quantum World of Visual Basic from 
the Other Side of the Looking Glass. 


Enlightening and entertaining! 


ETN Corporation 
RR 4, Box 659, Montoursville, PA 17754-9433 
Tel: (717) 435-2202 Fax: (717) 435-2802 
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Hipparchus™ GIS Enabling Technology 


Over 250 functions provide C developers with breakthrough 

GIS capabilities. Interface with any GUI and any DBMS. Ellipsoidal 
vector algebra enables seamless 

global coverage, lightning-fast 

spatial indexing, polygon overlay 

and more! 


DOSWindows Libraries, Application 
Prototyper, Tutorial (270 pp), 
Reference (340 pp): $475. Most 
other platforms supported 





Geodyssey Limited 

500, 815 Eighth Avenue SW, 
Calgary, Alberta, Canada T2P 3P2 
4()3-234-9848 Fax 403-266-7117 
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P.O. Box 338, Pennington, NJ 08534 


(800) 800-6613 * (609) 683-5501 « Fax: (609) 683-5502 
info @infomagic.com 


See us at the 
SD Conference, Booth 1747 


INGRAF 6.00 


A Multi-Device Graphics Library for Scientific, 
Engineering applications. Supports Video Gncluding 
SuperVGA), Printers and Pen Plotters. BASIC, C, 


FORTRAN-77 & PASCAL bindings. 
DOS Extender versions available. 


FULL SOURCE CODE 
NO ROYALTIES 


Sutrasoft 

PO. Box 1733 

Sugar Land, TX 77487 
Tel: 713-491-2088 
Fax: 713-240-6883 


NORAL 


SAAS: 


Automates conversion, Converts between: DB2, 
migration, duplication and DB2/2, SQL/DS, SQL Server, 
redesign deployment of all or Sybase, Oracle, Informix, XDB, 


alae oe sail Ingres, SQLBase and more. 
Converts and migrates SQL 


DDL, data, columns, indexes, | Call us for more information: 


referential integrity and nes a (206) 450-0815 


Schedules source database 
object and data movements 


Windows interface is intuitive, 


easy to use and consistent | 
across DBMS platforms N Syste ms 


Boost Your Turbo 
Productivity 


Award winning tools and libraries 


for Windows and DOS give your 

productivity a tremendous boost. 
Use interfaces, database access, 

comms, systems-level tools, and 

more. Call toll-free to get a FREE 
catalog. 


1-800-333-4160 


TurboPower Software 

P.O. Box 49009 

Colorado Springs, CO 80949-9009 
Int 719-260-9136 Fax 719-260-7151 


Gain the Competitive Edge 


ARC++ enhances your current C++ 
development environment: 


* Exportable classes simplify coding 
and maintenance 
Packages and overloaded enumerators 
streamline naming conventions 
Automatic functions allow “idiot-proof” 
Class libraries 
User-defined operators make code more readable 
Custom versions to suit your specific needs 
Multiple platforms supported 
And more... (800) 257-0073 


or (301) 459-3773 ext. 263 


AkSoftware Fax (301) 459-3776 


. 8201 Corporate Drive, Suite 1110 
Electronic Publishers and Distributors Landover, MD 20785 USA 


YOUR SOFTWARE'S 
THE WORLD 


SOFTWARE TRANSLATION SYSTEM 
PROCESS MANAGEMENT TOOL 


French, German, Spanish, Japanese 
and many more languages... 


@ Reduce Translation Time and more @ Provide Version Control 

@ Maintain Quality Control @ Use Glossary Management Tools 

@ Manage Multilanguage Projects | @ Use Stand-Alone Translator Workstations 
@ Reuse Prior Translations or Unlimited Run-Time License 


(| 2° FOR DOCUMENTS AND HELP FILES! 
oan MIF, RTF, Windows Help, ASCII, Interleaf and more J 


10474 Santa Monica Blvd., Suite #304 

Los Angeles, CA 90025 USA 

Tel : (310) 441-1024, Fax: (310) 441-0824 
° — Compuserve 73362,1175 


The Language Technology Company 








The Advanced SCSI 


Programming Interface 





into your code 





Brian Sawert 


n the near future, as CD-ROM drives, 

optical drives, and scanners become 

standard fare, SCSI devices will like- 

ly dominate the PC peripheral mar- 
ket. And as the market for SCSI pe- 
ripherals grows, so will the demand for 
software that supports them. 

But SCSI is not without its downside. 
SCSI protocol has generally been com- 
plex, a clear-cut standard for SCSI PC 
hardware has yet to emerge, and DOS 
doesn’t offer direct support for SCSI. The 
Advanced SCSI Programming Interface 
(ASPI), however, offers a straightforward 
way to build SCSI capability into your 
code. In this article, I'll examine the ASPI 
standard and discuss how to use ASPI 
to solve SCSI-support problems. 


The Problem with SCSI 
Although the SCSI standard defines a 
communications protocol and a com- 
mand set, the missing link for the DOS 
programmer is the interface to the SCSI 
bus. If you tackle the problem through 
low-level hardware programming, you 
restrict your software to a particular type 
or class of SCSI host adapter. 

ASPI, proposed by Adaptec, defines 
a set of high-level functions for com- 
municating with devices attached to the 
SCSI bus. It’s designed to protect you 
from the pitfalls of hardware-level pro- 
gramming and provide a standard in- 
terface to SCSI host adapters. 


Brian is an independent programmer 
specializing in device drivers and soft- 
ware for SCSI peripherals. He can be 
reached at bsawert@grdpnt flagstaff 
.aZ.us Or on CompuServe at 72027,2145. 
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The Advanced SCSI Programming 
Interface 
Adaptec, Trantor, and Future Domain all 
offer ASPI compatibility with their host 
adapters, ensuring hardware indepen- 
dence and a broader market for software 
written to the standard. Even unusual host 
adapters such as Trantor’s MiniSCSI par- 
allel-port adapter offer ASPI support. 
ASPI offers many advantages to the 
SCSI programmer. Because it is widely 
supported, it provides hardware and plat- 
form independence. Furthermore, ASPI 
manager software is available for DOS, 
OS/2, Novell NetWare, and other oper- 
ating systems. Best of all, ASPI provides 
a high-level function set that’s easy to 
use and can dramatically shorten your 
development time. ASPI hides the inner 
workings of SCSI protocol from the pro- 
grammer. The ASPI manager handles the 
eritty details of arbitration, selection, and 
message passing, returning status codes 
and sense data when appropriate. You 
still need a basic knowledge of SCSI 
structures and protocol to use ASPI ef- 
fectively, but it can shorten your learning 
curve by making experimentation easy. 
ASPI does have its shortcomings. For 
example, the ASPI manager does not 
return a transfer count. If your device 
does not support the illegal-length in- 
dicator GLI) and residual count in the 
sense data, there’s no way to check how 
much data was transferred. Some ASPI 
managers fail to recognize certain de- 
vices, restricting the operations you can 
perform on them. And the number of 
different status codes returned by an 
ASPI call requires additional error check- 
ing by the calling program. 


How ASPI Works 

Under DOS, ASPI takes the form of a 
character device driver. The driver in- 
stalls the ASPI manager—a device 
named $SCSIMGR. At startup, the ASPI 
manager polls the SCSI bus, looking for 
attached devices. A device must be 
turned on before bootup in order for 
ASPI to recognize it. The only time you 








access the ASPI driver through DOS is 
when you initialize it. At other times, a 
far call to the ASPI-manager entry point 
gives access to the ASPI function set. 
This makes ASPI functions safe to use 
from within a device driver or memory- 
resident program. 

Using ASPI requires knowledge of the 
SCSI command set and capabilities for 
the device you wish to support. Keep 
in mind that ASPI provides interface 
functions, not high-level SCSI functions. 
The ASPI manager merely passes data 
through to the SCSI device without mod- 
ifying or inspecting it. A point of con- 
fusion sometimes arises because ASPI 
parameters such as transfer length are 
in Intel order, while SCSI command- 
descriptor block (CDB) parameters ap- 
pear in order of MSB to LSB. 

The ASPI function set is small, but 
powerful. Some of the functions return 
information about the driver and envi- 
ronment, while others actually commu- 
nicate with the SCSI device. The ASPI 
specification defines the functions in 
Table 1. Probably the most useful func- 
tion in the ASPI set is Function 2 (exe- 
cute SCSI I/O request). This function 
passes a SCSI CDB to the device, han- 
dles data transfer, and returns messages 
and status codes. If the request results 
in a Check Condition status, ASPI re- 
quests sense data from the device, mak- 
ing it available to the calling program. 
Consider this function a direct channel 
to the SCSI bus, as you will use it for 
most of your SCSI requests. 

To initialize the ASPI manager, get a 
file handle to the ASPI driver by issuing 
(continued on page 158) 





Function —_ Descriptio 





Function 0 
Function 1 
Function 2 
Function 3 
Function 4 
Function 5 
Function 6 


Host-adapter inquiry 

Get device type 
Execute SCSI I/O request — 
Abort SCSI I/O request - 
Reset SCSI device 


Set host-adapter parameters 
Get disk-drive parameters | 


Table 1: ASPI functions. 
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(+ + DATABASE 
DEVELOPMENT 


Al Stevens 
Al Stevens, the popular Dr. Dobbs 
columnist provides all the tools you 
need to explore the full potential of the 
C++ object-oriented language. Learn 
to use C++ to design and develop utili- 
ties and database management 
programs. Topics include database fun- 
damentals and design, database man- 
agement, building the software, and 
much more. 

sa 


$49.95 1-55828-215-7 
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AL STEVENS 


( DATABASE DEVELOPMENT 

2nd Edition 

Al Stevens 
Noted author Al Stevens shows you 
how to master C database development 
using ANSI Standard C language to 
design and develop programs. Acquire 
an understanding of data structures by 
using this comprehensive reference that 
includes a library of database manage- 
ment functions. 


$49.95 & 1-55828-135-5 


For those who want to learn the basics... 


TEACH YOURSELE...series 


* Comprehensive coverage for the 
beginning computer user 

* Covers all major categories and subjects 

* Two-color interior for ease of use 


your lingertips 


SERIAL 


COMMUNICATION 
NG AND ++ 





Mis. 
WARK CHODHEY 


SERIAL COMMUNICATIONS IN 
( AND C++ 
Mark Goodwin 


Written by a leading expert in personal 
computer programming, this powerful, 
intuitive book explores the essentials of 
serial programming in C and C++. 

The extensive sample codes included 
on the disk allow you to build a pro- 

gram from start to finish. 


$49.95 @ —=1-55828-203-3 


Available at your 
local bookstore 


Your source for 
computer books 





Teach Yourself G+ + 9. 
3rd Edition ——_ 
a $29.95/1-55828-250-5 
MIS: PRESS 
| ns ai A Subsidiary of 
| , Teach Yoursell ( Henry Holt and Company, Inc. 
er 2nd Edition 115 West 18th Street 
| i Ba, $21.95/1-55828-252-1 New York, NY 10011 
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fr || ED-the 
=, programmer's editor 





The most advanced and truly configurable 
editor available today for DOS and Windows 


The right editing environment can make or break 
your development schedule. ED, the programmer’s 
editor was carefully designed to optimize the task of 
code entry and maintenance. ED’s extensive fea- 
ture set includes a full suite of block operations, 
multi-file search/replace, smart indenting, and 
color syntax highlighting. You can even run your 
compiler and view errors in place without leaving 
the editor. Of course, no amount of features can 
compensate for an environment that’s not comfort- 
able to work in. That’s why ED provides built-in 
emulations for all the popular editors, plus ultimate 
flexibility to remap keys and menus. And if you still 
need more, a C extension language and source code 
give you the power to create a totally customized 
and interfaced development environment. 


Features: 


¢ Language support includes C/C++,dBASE, 
Clipper and Pascal 

¢ Emulates all popular editors including 
BRIEF and Norton 

¢ Fully configurable menus and keyboard 

¢ Common Windows/DOS interface 

¢ Error tracking displays compile errors in 
place in the source 

¢ Maintains working environment between 
edit sessions 

¢ Multiple windows and multiple files in 
a window 

¢ Virtual memory manager allows editing of 
huge files 

e Extensive search/replace functionality 
including regular expressions 

¢ Hypertext function/procedure lookups 

¢ Comprehensive context-sensitive help 

¢ Keyboard macros and remapping 

¢ Rectangular column blocks plus stream 
and line blocks 


Pricing: 

ED for Windows $249 
ED for DOS $199 
Professional version 

(DOS and Windows) $349 
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=... Dan Bricklin’s® Demo II 








The leading Demo and Prototyping Tool for DOS 


The best way to sell a product is to put your customer in the driver’s seat. Demo II 
allows you to quickly translate abstract ideas into a visual reality. With Demo II, you 
have the power to create a winning demonstration that conveys all of the fine points 
of your product. Choose a demo that is interactive or self-running, and dress it up with 
menus, graphics and snapshots of your application. Demo II is also ideally suited to 
rapid prototyping as well as creating computer—based product tutorials. 


Features: 


¢ Proven product — over 40,000 satisfied users 

e Graphics and text mode support 

¢ No programming required 

e Interactive screen designer 

e Screen grabber to include “snapshots” of existing programs 

¢ Develop slide shows 

e Interactive or self-running demos 

¢ SVGA, VGA, EGA graphics and animation 

¢ Full and partial PCX imaging 

e Variety of font styles and sizes 

¢ Development kit includes: Demo II Professional, John Bickart’s Starter Kit, Clip 
Art and CBT (computer-based training) Tool Kits for Demo I] 


Pricing: 
Standard $249 
Professional $399 


Development Kit $599 


Essential Chart for Windows 





The most powerful and easiest way to develop charts for Windows 


A graphical presentation of data adds important appeal and utility to any application. 
Essential Chart makes your data come alive in full color 2D or 3D, static or real-time 
charts and graphs. This comprehensive Windows DLL adds extensive functionality 
including true 3D rotation and perspective, and the ability to scale text using built-in 
True-Type font support. Plus, a powerful, time-saving CASE tool allows you to inter- 
actively create and design charts and chart templates without programming. 


Features: 


e 18 different chart types 

¢ 2D and 3D bar, pie, pyramid, ribbon and area charts 
¢ Financial and analysis chart types 

e True 3D perspectives and rotations 

¢ Real-time charting with live data 

¢ Supports True-Type fonts for text scaling and resizing 
e Windows printer support 

e Displays chart in a parent or child window 

¢ Source available 


Pricing: $249 
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object-Menu 
The cross—platform application framework for C++ 


A good interface design can be the deciding factor 
in today’s competitive marketplace; object-Menu 
makes it happen in several ways. Built-in aesthetics 
make it easy to create interfaced styling such as 
Windows, Motif, or your own custom design. 
Flexible interface configuration allows you to mold 
the interface to the application, not the other way 
around. And, portability to DOS, Windows/NT 
and OS/2 enable you to offer your product to multi- 
ple target markets with a single engineering effort. 
Additionally, object-Menu’s intuitive architecture, 
straightforward methodology and Visual Design 
tool actually speed GUI development to allow 
more time to focus on your application. 


Features: 


¢ Currently supports DOS graphics, 
Microsoft Windows, Windows NT and OS/2. 

e Visual Design Tool included with automatic 
code generation 

e Extensive “behind the scenes support” keeps your 
programs small and easier to debug and maintain 

¢ Comprehensive set of interface and graphics 
objects including multi-media objects 

¢ Supports multiple browsers or child windows off 
the main application 

e Extensive data entry capability including real 
time field formatting and validation as well as 
unlimited data types 

¢ Hypertext help system with help authoring plus 
hypertext primitives 

¢ Intermix graphical icons with menus, 
buttons, text 

¢ Includes the MetaWindow/XL high performance 
graphics library 

¢ Supports major C++ compilers and all popular 


DOS graphics libraries 


Pricing: 

Single platform (choose DOS, 

Windows, NT or OS/2) $299 
Single platform with source $449 


object-Menu Professional 


(DOS, Windows/NT with source) $699 
object-Menu Professional-OS/2 
(DOS, Windows/NT, OS/2 with source) $899 


CALL to ORDER 
800-447-1955 
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(continued from page 154) 

a DOS open call to the $SCSIMGR de- 
vice. Next, use a DOS IOCTL read to 
obtain the ASPI entry-point address. This 
is a far address you call to execute any 
of the ASPI functions. Last of all, close 
the file handle. You won’t need to ac- 
cess the driver through DOS again. List- 
ing One (page 159) illustrates these 
steps. 

All ASPI functions use a SCSI request 
block (SRB). The SRB has a common 8- 
byte header for each function, contain- 
ing an ASPI command code (see Table 
2), host-adapter number, and request 
flags. The header also contains a status 
byte that the ASPI manager uses to re- 
turn the outcome of the ASPI request. 
Calling an ASPI function requires filling 
in the proper SRB for the function, push- 
ing the far address of the SRB on the 
stack, and making a far call to the ASPI 
entry point. 

Functions that only access the ASPI 
manager return immediately. Functions 
that communicate with the SCSI device 
may return with the status byte set to 
QO, indicating that the request is still in 
progress. ASPI offers two methods for 
determining whether a SCSI request has 
completed: polling and posting. Polling, 
as the name implies, simply means pe- 
riodically checking the status byte for a 
nonzero value. Posting, on the other 
hand, tells the ASPI manager to execute 
a post-processing routine when the SCSI 
request has completed. You enable post- 
ing by setting the Post bit in the request 
flags and passing the address of the rou- 
tine in the SRB. The ASPI documenta- 
tion recommends that applications use 
polling, reserving posting for device 
drivers or TSR programs, which may be 
interrupt driven. 


SCSI 1/O Under ASPI 
The most complex function in the ASPI 
specification is also the most powerful. 
















Command Code 0 
Host-adapter Inquiry 
host adapter. 


Command Code 1 
Get Device Type 


Command Code 2 
Execute SCSI I/O Request 


Command Code 3 
Abort SCSI 1/O Request 
Command Code 4 
Reset SCSI Device 


Command Code 5 
Set Host-adapter Parameters 


Command Code 6 
Get Disk-drive Information 


Table 2: The ASPI DOS specification. 
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Returns information about installed host adapters: the n 
adapters instal ee and strings identifying the ASPI man 


Returns the peripheral device type code for the device « at ¢ a 
given SCSI target ID. 


Executes a SCSI command, passing a CDB toa device and 
managing data transfer and status return. Requests sense data 
if a Check Condition status occurs. 


Aborts a pending SCSI operation. 
Resets the device at a given SCSI target ID. 


Sets unique parameters for a host adapter. Few manufacturers 
implement this function. 


Returns information for a SCSI disk drive. Returns preferred head 


and sector translations and flags for INT 13h support. This _ 
is a recent addition to the ASPI spec and is not widely supported. 


Function 2 (execute SCSI I/O request) 
is the gateway to the SCSI bus. The SRB 
for this function contains the data-buffer 
address and size, the target SCSI ID, and 
the SCSI CDB. Function 2 is also the 
most awkward to use. In addition to the 
ASPI status byte, it returns status codes 
for both the host and the target device. 
It also returns sense data if the SCSI re- 
quest produces any. Finding the sense 
data can be tricky. It does not reside at 
a fixed offset in the SRB, but appears 
immediately after the SCSI CDB. You 
must keep track of the size of the CDB 
to locate the sense data. Once you are 
aware of these issues, using this func- 
tion becomes quite simple. Just fill in 
the SRB, call the ASPI entry point, and 
watch the status byte until the request 
completes. Listing Two (page 159) dem- 
onstrates how to call the ASPI I/O func- 
tion using polling. 


ASPI Under Windows 

Using ASPI under Windows is a bit more 
complex. Because the ASPI manager ex- 
pects real-mode addresses in segment: 
offset form, the protected-mode selec- 
tor:offset type of address will not work 
properly. You must pass real-mode ad- 
dresses for the SRB and data buffers. 

The entry-point address the ASPI man- 
ager returns is also a real-mode address. 
This means that under protected mode, 
you cannot call this address directly. 

The solution to both problems is to 
use Windows’ DPMI services, but there 
is a catch here that may not be obvi- 
ous: These services are not available to 
a Windows application; you can only 
use them from within a DLL. 

If you’re starting to get discouraged, 
take heart. Accessing the ASPI manager 
requires only three DPMI functions. 
Function 100h (allocate DOS memory 
block) and function 101h (free DOS 
memory block) manage real-mode mem- 
ory for the ASPI SRB and data buffers. 


The Windows functions GlobalDOSAlloc 
and GlobalDOSFree use these services, 
and they are easier to work with than 
the corresponding DPMI functions. Be 
careful, however, that you don’t use real- 
mode buffers too freely. Allocating real- 
mode memory means taking it from the 
address space below 1 megabyte, where 
memory is a limited resource. 

The only DPMI function you must use 
directly is function 301h (call real-mode 
procedure with far-return frame). Since 
the ASPI entry point is a real-mode ad- 
dress, you risk a protection fault if you 
try to call it from within Windows. Func- 
tion 301h lets you call the entry point 
from protected mode, although the pro- 
cedure is somewhat cumbersome. The 
calling function must fill a structure with 
register values for the real-mode pro- 
cedure and set up a stack for passing 
parameters. The DPMI server can pro- 
vide a default stack, but the size is lim- 
ited. Stack usage may vary between 
ASPI drivers, so you may wish to pro- 
vide your own. 

Listing Three (page 160) recasts the 
call to the ASPI entry point as a DLL 
function. The call requires some inline 
assembly code and uses the DPMI de- 
fault stack for simplicity. The real-mode 
call structure duplicates the 32- and 16- 
bit CPU registers. Setting up the call re- 
quires filling the CS:IP fields in the struc- 
ture with the real-mode address of the 
ASPI entry point. Pass the pointer to the 
SRB on the protected-mode stack, set- 
ting CX to the number of words pushed. 
The DPMI server will create a real-mode 
stack with these parameters. Last of all, 
execute an INT 31h to call the procedure. 

If you want to know more about 
DPMI functions, download the DPMI 
spec from the CompuServe Intel forum. 
For examples of using Windows DPMI 
services, look in the Microsoft Software 
Library on CompuServe. 


Conclusion 

The complete listings (available elec- 
tronically, see “Availability,” page 3) for 
these examples include source code for 
an ASPI library and an application to in- 
ventory the SCSI bus. For Windows pro- 
grammers, the listings also include 
source code for an ASPI DLL. 

If you want to investigate ASPI fur- 
ther, Adaptec sells the ASPI Software 
Developer's Kit, which contains the spec- 
ification and programming guides for 
DOS, Windows, OS/2, and NetWare, as 
well as utilities and sample code. (Call 
Adaptec at 800-442-7274 or call their 
BBS at 408-945-7727.) 


DDJ 
(Listings begin on page 159.) 


To vote for your favorite article, circle inquiry no. 16. 
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Listing One (Listing continued, text begins on page 154.) 


// —— Initializing the ASPI driver. —— 

#include “aspi.h” // ASPI definitions and constants 

#include “scsi.h” // SCSI definitions and constants 

// —————— defines and macros 

#define IOCTL_READ 2 

#define ASPI_NAME “SCSIMGRS” 
global variables 

void (far *ASPIRoutine) (aspi_req_t far *); // far address of ASPI routine 

BYTE f_installed; // flag for ASPI existence 


// IOCTL read function 
// SCSI manager driver name 


aspi_req_t *srb; // SCSI Request Block pointers 
// Routine to check for and initialize ASPI driver. 

// Usage: int aspi_open(void) ; 

// Returns nonzero on success, @ if ASPI driver not found or init failed. 
int aspi_open(void) 


int dh; // ASPI driver handle 
if (!f_installed) 
{ // not initialized 
if ((dh = open(ASPI_NAME, O_RDONLY | O_BINARY)) != -1) 
{ // open device driver 
if (ioctl(dh, IOCTL_READ, (void *) &ASPIRoutine, 
sizeof (ASPIRoutine)) == sizeof (ASPIRoutine) ) 
{ // got ASPI entry point 
srb = (aspi_req_t *) malloc(sizeof(aspi_req_t)); 
if (srb != NULL) 
{ // allocated SRB buffers 
f_installed++; // set installed flag 
} 


close (dh) ; // close device driver 
} 
} 
return(f_installed) ; 
} 
i/ 
// Routine to close and clean up. 
// Usage: void aspi_close(void) ; 
// Called with nothing. Returns nothing. 
void aspi_close (void) 
t 
if (f_installed) 
{ // already initialized 
free(srb) ; // deallocate buffers 
f_installed = @; // clear installed flag 
: 
return; 


} 


BACK ISSUES 


Call now to order your back issues of 
DR. DOBB’S JOURNAL: 


(800) 444-4881 


Mail Orders: P.O. Box 105448, Atlanta, GA 30348-5448. 
Copies are $7 each, Canada & Mexico $9.00; all others $11. 
Sales tax required on all orders for NY, MA, GA, and CA, 
For foreign orders call 1-404-426-1926. 
Call for volume discount prices. 
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ASPI 


Listing Two 


// — Calling the ASPI entry point and ASPI 1/0. ——- 
#include “aspi.h” // ASPI definitions and constants 
#include “scsi.h” // SCSI definitions and constants 


// —————— defines and macros 
#define BUSY_WAIT  @x1@@@ 

#define MIN_GRP_1 Ox2@ 

// ———— global variables 

void (far *ASPIRoutine) (aspi_req_t 
BYTE f_installed; 

BYTE aspi_stat; 

BYTE host_stat; 

BYTE targ_stat; 

BYTE host_num; 


// repeat count for busy check 
// minimum SCSI group 1 command 


*); // far address of ASPI routine 
// flag for ASPI existence 

// ASPI status byte 

// host status byte 

// target status byte 

// host adapter number (% default) 


// SCSI Request Block pointers 
// pointer to SRB sense data 


aspi_req_t *srb; 

5 pea *srb_sense; 
// Routine to call ASPI driver. 

// Usage: int aspi_func(aspi_req_t *ar); 

// Called with pointer to SCSI Request Block (SRB). 
// Returns nonzero on success, @ on error. 

int aspi_func(aspi_req_t *ar) 





int retval = @; 


if (f_installed) 
{ // ASPI manager initialized 
ASPIRoutine((aspi_req_t far *) ar); // call ASPI manager 
retval+t+; 
} 
return(retval) ; 
} 
|| 
// Execute SCSI I/O through ASPI interface. 
// Usage: int aspi_io(BYTE *cdb, BYTE far *dbuff, WORD dbytes, 
// BYTE flags, BYTE id, WORD *stat); 
// Called with pointer to data buffer, data buffer size, pointer to CDB, 
// request flags, and target ID. Returns ASPI status on success, -1 on error. 
// Fills stat variable with host status in high byte, target in low byte. 
int aspi_io(BYTE *cdb, BYTE far *dbuff, WORD dbytes, BYTE flags, 
BYTE id, WORD *stat) 
{ 
int cdbsize; 
int timeout; 
int retval = -1; 


// timeout counter for polling 


memset (srb, @, sizeof(aspi_req_t)); // clear SRB 
srb->command = SCSI_IO; // set command byte 


(continued on page 160) 








159 


Listing Two (Listing continued, text begins on page 154.) 


srb->hostnum = host_num; // set host adapter number 
srb->su.s2.targid = id; // set target SCSI ID 
srb->reqflags = flags; // set request flags 
srb->su.s2.databufptr = dbuff; // set pointer to data buffer 
srb->su.s2.datalength = dbytes; // set data buffer length 


srb->su.s2.senselength = sizeof(sense_block_t) ; 
// set sense data buffer length 

cdbsize = sizeof(group_@_t) ; // assume 6 byte CDB 
if (*((BYTE *) cdb) >= MIN_GRP_1 && *((BYTE *) cdb) < MIN_GRP_6) 

{ // CDB size is 19 bytes 

cdbsize = sizeof (group_1_t) ; 

} 
srb->su.s2.cdblength = cdbsize; // set CDB length 
srb->su.s2.senselength = MAX_SENSE; // sense sense data length 
memcpy (srb->su.s2.scsicdb, cdb, cdbsize); // copy CDB to SRB 
srb_sense = srb->su.s2.scsicdb + cdbsize; 
if (aspi_func(srb) ) 

{ // ASPI call succeeded 

timeout = BUSY_WAIT; // set timeout counter 


while (srb->status == REQ_INPROG && timeout > @) 


{ // request in progress - keep polling 


timeout-; // decrement timeout counter 
} 
retval = aspi_stat = srb->status; 
if (aspi_stat != REQ_INPROG) 
{ // request completed 
host_stat = srb->su.s2.hoststat; // save host status 
targ_stat = srb->su.s2.targstat; // save target status 
*stat = ((WORD) host_stat << 8) | targ_stat; 
// return combined SCSI status 
} 


// save ASPI status 


} 
return(retval); 


} 


Listing Three 


// —— Initializing and using ASPI in a DLL. — 

#include “aspi.h” // ASPI definitions and constants 
#include “scsi.h” // SCSI definitions and constants 
// —————— defines and macros ——————- 

#define IOCTL_READ 2 // IOCTL read function 

#define ASPI_NAME “SCSIMGRS” // SCSI manager driver name 
#define DPMI_INT Ox31 // DPMI interrupt number 

#define REAL_CALL @x3Q@1 // real mode call function 


typedef struct RealCall 
{ // struct for real mode call 
DWORD edi, esi, ebp, reserved, ebx, edx, ecx, eax; 
WORD flags, es, ds, fs, gs, ip, cs, sp, ss; 
} RealCall_t ; 
// —————— global variables —————_- 
void (far *ASPIRoutine) (aspi_req_t far *); // far address of ASPI routine 


// point to sense data buffer 


ASPI 


// 


// Routine to call ASPI driver. 
// Usage: 


int aspi_func(aspi_req_t _FAR *ar); 


// Called with pointer to SCSI Request Block (SRB). 
// Returns nonzero on success, @ on error. 


int aspi_func(aspi_req_t _FAR *ar) 
{ 
aspi_req_t far *arptr; 
int retval = @; 
if (f_installed) 
{ 


// real mode pointer 


// ASPI manager initialized 


if ((arptr = (aspi_req_t far *) MaptoReal(ar)) != NULL) 


/ got a valid real mode pointer 


retval = AspiCall(ASPIRoutine, arptr); // call ASPI through DPMI 


{ 
} 
} 
return(retval); 


} 
// 


// Usage: 


// Routine to map protected mode pointer to real mode. 
void far *MaptoReal(void far *pptr); 


// Returns real mode pointer on success, NULL on error. 


void far *MaptoReal(void far *pptr) 
{ 
WORD sel; 
void far *ptr = NULL; 
sel = FP_SEG(pptr) ; 
if (sel == LOWORD(dwPtr) ) 


// protected mode selector 
// real mode pointer 
// get selector value 
// found matching selector 


// build real mode pointer 


{ 
ptr = MAKELP(HIWORD(dwPtr), FP_OFF(pptr)); 
} 

return(ptr) ; 


} 
// 


// Call ASPI manager through DPMI server. 


/ Usage: int AspiCall(void far *aspiproc, aspi_req_t far *ar); 


// Returns 1 on success, @ otherwise. 


int AspiCall(void far *aspiproc, aspi_req_t far *ar) 


{ 

RealCall_t res; 
int retval = @; 
int npush; 

void far *sptr; 


memset (&res, @, sizeof(RealCall_t)); 


res.cs = HIWORD(aspiproc) ; 
res.ip = LOWORD(aspiproc) ; 


// real mode call struct 


// clear call structure 
// point to real mode proc 


npush = sizeof(aspi_req_t far *) / sizeof(WORD); // words to pass on stack 


sptr = (void far *) &rcs; 
asm { 

push di 

push es 

sub bx, bx 

mov cx, npush; 

les di, sptr 

mov ax, REAL_CALL 

push WORD PTR [ar + 2] 


/ far pointer to call structure 
// save registers 


// don’t reset A2@ line 

// number of words to copy to stack 
// point ES:DI to call structure 

// load function number 

// push SRB address 


BYTE f_installed; 
aspi_req_t _FAR *srb; 
DWORD dwPtr; 


// flag for ASPI existence 
// SCSI Request Block pointers 
// return from GlobalDOSAlloc 


push WORD PTR [ar] 
int DPMI_INT // call DPMI server 


// ————— local functions ——————- 
void far *MaptoReal(void far *pptr); // map to real mode address 
int AspiCall(void far *aspiproc, aspi_req_t far *ar); // DPMI function 


// Routine to check for and initialize ASPI driver. 

// Usage: int FUNC aspi_open(void); 

// Returns nonzero on success, @ if ASPI driver not found or init failed. 
int FUNC aspi_open(void) 


{ 
int dh; // ASPT driver handle 
UINT wSRB; // selector for buffer memory 
if (!f_installed) 
{ // not initialized 
if ((dh = open(ASPI_NAME, O_RDONLY | O_BINARY)) != -1) 
{ // open device driver 
if (ioctl(dh, IOCTL_READ, (void far *) &ASPIRoutine, 
sizeof (ASPIRoutine)) == sizeof (ASPIRoutine) ) 
{ // got ASPI entry point 
dwPtr = GlobalDosAlloc (sizeof (aspi_req_t)); 
if (dwPtr[@] != NULL) 
{ // allocated SRB buffer 
wSRB = LOWORD(dwPtr[@]); // extract selector 
GlobalPageLock(wSRB); // lock memory 
srb = (aspi_req_t _FAR *) MAKELP(wSRB, @); 
f_installed++; // set installed flag 
} 
} 
close (dh) ; // close device driver 
} 
} 
return(f_installed) ; 
} 


Vi 
// Routine to close and clean up. 
// Usage: void FUNC aspi_close (void) ; 
// Called with nothing. Returns nothing. 
void FUNC aspi_close(void) 

{ 


UINT wSRB; 

if (f_installed) 
{ // already initialized 
wSRB = FP_SEG(srb) ; // extract selector from pointer 
GlobalPageUnlock (wSRB) ; // unlock buffer 
GlobalDosFree (wSRB) ; // deallocate buffer 
dwPtr = NULL; 
srb = NULL; 
f_installed = @; 
} 

return; 


} 


// selector for buffer memory 


// clear installed flag 
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pop ax // restore stack count 
pop ax 

pop es // restore registers 
pop di 


je asm_exit 
mov retval, 1 
} 
asm_exit: 
return(retval); 


} 


// DPMI error 
// return 1 for success 


End Listings 
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Some people 
put the homeless out 
of their minds. 


Christine Vigil put 


them on-line. 





In 1906 St. Vincent de Paul was 
founded to help people left homeless by the 
San Francisco Earthquake. Today, they're 
an organization that helps thousands of 
homeless people nationwide. By finding them 
shelter, medical care, rehabilitation, and jobs. 

That’s where Christine came in. 
Before she got involved, St. Vincent de 
Paul worked with 75 other San Francisco 
social service agencies matching homeless 
people with available jobs. The Job Finders 
Alliance worked hard, but since they only 
communicated by memo and phone, it 
could take up to three weeks to match a 
qualified person with an open job. 

By using her computer skills, 
Christine was able to put St. Vincent’s 
on-line, and make the whole process more 
efficient. As a direct result of her efforts, 
today St. Vincent's has been able to find jobs 
for their people far more rapidly. And make 
better matches, because they have access 
to a comprehensive database. 

Of course Christine is just one 
example. There are a lot of ways you can 
put your special computer skills to a much 
appreciated use, whether you specialize in 
telecommunications, system debugging, 
or basic software training. To know more, 
call CompuMentor™ at 1-800-659-3579. 


We'll put you in touch with a local non- 





profit organization whose needs are 

compatible with your area of expertise. 
There are many ways to make a 

difference in the world. Sometimes it’s 


simply doing what you already do best. 
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89 Stillman Street, San Francisco, CA 94107 
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The Tool Interface Standards (TIS) 
Committee, a group of software com- 
panies working to advance the inter- 
operability and portability of develop- 
ment tools for 32-bit Intel architecture 
Operating environments, has announced 
version 1.1 of the TIS Portable Formats 
Specification. 

The TIS spec standardizes the first 
linkable, loadable, and debug formats. 
The formats include the relocatable ob- 
ject module format (OMF), executable 
linkable format (ELF), and debug in- 
formation format (DWARF). The com- 
mittee has also agreed upon Microsoft's 
PE and symbol and type information 
(STD for the Windows environment. 
Version 1.1 updates OMF and DWARF 
by clarifying inconsistencies in the 
OMF standard and adding functional- 
ity to the DWARF standard through 
support for C++, Fortran-90, Modula- 
2, and Pascal. 

TIS includes the aforementioned 
Portable Formats Specification for defin- 
ing file formats portable across Win- 
dows, UNIX, OS/2, and other operating 
systems, and the Formats Specification 
for Windows, which describes formats 
for 32-bit implementations of Windows. 
TIS-compliance enables you to mix- 
and-match tools that previously con- 
formed to proprietary interface specs. 
Companies backing TIS include Borland, 
IBM, Microsoft, Intel, SCO, Novell, Mi- 
crotec, Watcom, Lotus, Metaware, La- 
hey, Autodesk, SSI, and Absoft. 

Copies of the Tool Interface Standards 
specification are available on Compu- 
Serve (GO IntelAccess) or the Intel Lit- 
erature Center (order #241597). Reader 
service no. 20. 

Intel Corp. 

Literature Center 

P.O. Box 7620 

Mt. Prospect, IL 60056-7620 
800-548-4725 


BetterState from R-Active is a Windows- 
based visual programming tool for de- 
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veloping state machines which include 
concurrency and hierarchy. The tool’s 
graphical environment lets you draw 
states, identify threads of concurrent con- 
trol, and annotate diagrams. These dia- 
grams can be on one or more linked 
“pages.” 

Once a BetterState diagram is com- 
plete, the tool generates C, C++, VHDL, 
or Verilog HDL code. The software 
comes with templates for scheduling the 
design deterministically, stochastically, 
or using specific scheduling algorithms 
(round robin, for example). 

BetterState retails for $1195.00. Read- 
er service no; 21. 

R-Active Concepts 
20054 Gardenside Circle 
Cupertino, CA 95014 
408-252-2808 


The Windows API is rapidly becom- 
ing a de facto standard for program- 
mers developing under both UNIX and 
Windows. Joining the ranks of Bristol 
Technology’s Wind/U cross-platform 
development tool is Mainsoft’s Main- 
Win Cross-Development Kit which 
now supports VC++/MFC. (Wind/U is 
discussed in this issue’s article “Cross- 
Platform Development with Visual 
C++” by Chane Cullens, while the un- 
derlying technology to MainWin is dis- 
cussed in “Binary-Data Portability” by 
José Luu.) 

With the MainWin CDK, you can write 
a single code base using VC++/MFC on 
Windows or Windows NT, and re- 
compile it for Sun, IBM, HP, and SGI 
workstations and for X Terminals that 
support Motif. 

The MainWin Cross-Development Kit 
sells for $5000.00; discounts and licens- 
ing agreements are available. Reader ser- 
Vice NO, 22. 

Mainsoft Corp. 

883 North Shoreline Blvd., Suite C-100 
Mountain View, CA 94043 
415-966-0600 


A series of new app notes of interest to 
developers of testing, measurement, and 
control applications have been prepared 
by National Instruments. The notes, as 
you might expect, focus on National In- 
struments tools. 

The first app note, “VXI Block Data 
Transfer and Register-based Device Pro- 
gramming Using the GPIB-VXI,” dis- 
cusses the methods for transferring data 
between National Instruments’ GPIB 
controllers and VXIbus instruments 
linked by GPIB-VXI interface kits (part 
#340508-01). 

As its title suggests, “Measuring 
Temperature with Thermocouples” 
(part #340524-01) examines the use 
of thermocouples to measure tem- 


perature and how to avoid common 
problems. “Measuring Temperature 
with RTDs” (part #340557-01) ad- 
dresses how scientists and engineers 
are able to use the high-accuracy and 
stability of resistance-temperature de- 
tectors (RTDs) to measure a wide 
range of temperatures. 

“Signal Conditioning Fundamentals for 
PC-based Data Acquisition Systems” is 
an introduction to the fundamentals of 
using signal-conditioning hardware with 
PC-based data acquisition systems (part 
#340505-01). 

Other app notes covering topics rang- 
ing from DSP-based data acquisition to 
fast Fourier transforms for Windows ap- 
plications are available on request. Read- 
er service no. 23. 

National Instruments 

6504 Bridge Point Parkway 
Austin, TX 78730-5039 
512-794-0100 


The Kolibri Custom Control Library is a 
DLL that allows integration of 3-D Win- 
dows controls into C, C++, and Pascal 
programs. Kolibri consists of 12 control 
classes for animation, slider controls, 
swivel controls, list browse boxes for 
large databases, flexibutton controls, mo- 
tion controls, and so on. The Kolibri 
controls integrate direction into the Bor- 
land Resource Workshop, essentially be- 
coming an additional set of Resource 
Workshop tools. (Note that the library 
does not require the Borland compiler, 
however.) 

The Kolibri for VBX library provides 
similar functionality for languages that 
support VBXs— Borland C++ 4.0, Vi- 
sual Basic, and the like. 

Each library sells for $149.00, or 
$298.00 with source code. There are 
no run-time royalties. Reader service 
no. 24. 

European Software Connection 
P.O. Box 1982 

Lawrence, KS 66044 
913-832-2070 


The HTI Map Developer’s Kit from 
Horizon Technology is a set of three 
programming libraries that allow you 
to add detailed raster-mapping capa- 
bilities to any Windows- or DOS-based 
application. The Map Display Library, 
on which the Developer’s Kit is based, 
supports functions such as loading, 
displaying, zooming, and seamless 
scrolling through a database of geo- 
referenced raster maps. It also con- 
tains functions to convert geographic 
coordinates to screen coordinates and 

vice versa. 
In addition to the Map Display Li- 
brary, the Developer’s Kit includes the 
(continued on page 167) 
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Free Pentium. 
Optimization Guide 
Call or FAX for a copy of Quantasm’s Pentium Optimization 
Guide. Used by itself or with ASMFLOW Professional, you 
can obtain amazing performance increases. ASMFLOW 
automatically produces flow charts, call trees register analysis, 
data x-ref, timing and more. Available for 80x86, 8051, 8085, 


CANDELA COLOR 
MANAGEMENT SYSTEM 
COON hey) 


Your Best 
CDROMs! 


Cica MS WindowsCDROM 4000 new Windows programs - quarterly updates $ 29.95% 
Giga Games CDROM 3000 hot Games for MSDOS and Windows $39.95 











8096, Z-80, 6502, 68HC11 and 1750A. ($199.95) 
Call for free demo and catalog of assembly, TSR and floating 


point libraries. ($99.95 to $299.95) 


Quantasm Corp. 
19672 Stevens Creek Blvd #307-D 
Cupertino, CA 95014 
800-765-8086 or 408-244-6826 
FAX: 408-244-7268 
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Earn Your High-Tech Degree 
While Working Full Time 


New book High-Technology Degree Alternatives 


shows how to get your college degree without 
quitting your job, attending night school for years, 
or breaking your budget. All degree programs are 
accredited, and many do not require classroom 
attendance. Use VISA or M.C. $21.95 + $3.75 shh. 
Professional Publication Inc., Dept. 809. 


(800) 426-1178 
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Bug Tracking Made Easy 


Soffront® TRACK™ is a client-server based 
ready-to-use Bug-tracking and Technical Support 
system for Windows™. Using TRACK you can 
record a Bug, System, and Customer information, 
query, produce reports, notify other users, keep a 
log of change history, import, export, and more. 
Customize forms, fields, views and reports to 
meet specific needs of your organization. 


Soffront Software 
1806 Milmont Drive, Suite # 169, Milpitas, CA 95035 
Call 1-800-SOF-FRONT / (408) 263-2703 
or Fax (408) 263-7452 
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& OPERATING SYSTEMS FOR $39.95 


The LARGEST COLLECTION of source for compilers, function libraries, 
and docs for standard and research languages & OS ever assembled. 
..Ada, Basic, C, C++, E, ET++, Lisp, Mach, Modula, Oberon, Pascal, 
Prolog, Rexx, Sather, Scheme, Self, Simula, Tcl, Yacc, etc... 


Language/OS CD-ROM $39.95 
Other Titles Available 


Graphics — 1 (Applications w/ source) $24.95 
Audio — 1 (Applications w/ source) $24.95 
Multimedia — 1 (Applications w/ source) $49.95 


Knowledge Media 

436 Nunnely Rd., Ste B, Paradise, CA 95969, USA 
1-800-78-CD-ROM VISA/MC/COD 
+1-916-872-3826 Voice/FAX 
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“ 
640 MB OF SOURCE FOR LANGUAGES 


Space and Astronomy CDROM Thousands of NASA images and data files $39.95 
C User Group Library CDROM ——Acollection of user supported C source code $ 49.954 
Simtel MSDOSCDROM Classic: 650 MB Shareware / Freeware for MSDOS $29.95 
QRZ! Ham Radio CDROM FCC Callsign Database for Win & DOS + files $ 29.95% 
Gifs Galore CDROM 6000 mostly 640x480 GIF Images in every catagory $39.95" 
Gutenberg Project CDROM Classic Literature and historical documents $39.95 
Hobbes OS/2CDROM —600 MB always current Shareware/Freeware for OS/2 $29.95* 
Source Code CDROM —-650 MB of Unix & DOS sourve code for programmers $ 39.95* 
Intemet Info CDROM Thousands of computer, net, and intemet documents $39.95 
X Windows and GNU software for Unix and SPARC $39.95 


GEMini ATARI CDROM 
Ada CDROM 

Nova for NEXTCDROM 
Nebula for NeXTSTEP Intel 
Garbo MSDOS/Mac CDROM 
Fractal Frenzy CDROM 
FreeBSD CDROM 
Linux CDROM 


600 MB black NeXT app's, stc,, docs, ete $59.95* 
600 MB NeXTSTEP Intel app's, docs, etc $59.95* 
MSDOS and Macintosh Shareware/Freeware $29.9 

2000 high resolution fractals - royalty free $39.95 
Berkeley BSD. 32bit O/S for PC, w/ GNU & X11. Swe $39.95 
Yggdrasil Linux. 32bit O/S for PC, w/ GNU & X11.Ste $49.95 
MSDOS, 0S/2, Windows. Spanish descriptions $39.95 
Berkeley’s experimental Distributed OS for Sun’s $29.95 


CDROM Caddies Standard type, highest quality, Lifetime guarantee! $ 4.95 


1-800-786-990 





All our CDROMs are 
unconditionally guaranteed. VBA 
*Shareware 


mesmscaie Walnut Creek CDROM 


Hpaltne found 4041 Pike Lane, Suite D-391 Concord, CA 94520 


isefy FAX: 1-510-674-0821 email: orders@cdrom.com 
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Basic to C 
BAS_C v6.0 translates BASICA/QBASIC/ 
Quick BASIC source code to C source 
code automatically. The translated C 
source code is scoped, indented, 
structured, syntax error free and can be 
compiled Turbo/Borland/Microsoft/Quick 
C. Runtime C source code is available. 
90% conversion ratio. From $599. 
Call for non-MS Basic. 


Gotoless Coversions 
7105 Dee Cole Dr. 
Colony, TX 75056 
(214) 625-2323 
BBS: (214) 625-6905 FAX: (214) 370-2612 
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AWKtoC for MS-DOS 


Get the execution speed and security 
needed with your @WK scripts. Code 
faster in @WK for simplicity then use 
ASPEN's_AWKtoC to create compilable C 


Only $149.00 MC/VISA 
Call 201-316-0866 or Fax 201-334-7896 


source code. 


ASPEN Technologies, Inc. 
FO Box 6727 
Parsippany, NJ 07054 
Site Licenses available - Money back guarantee 
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SOURCE CODE FORMATTERS 


CleanClipper $69 CleanPascal $69 


indentation ~ operator spacing ~ function statement 
spacing ~ control statement spacing ~ code-block 
spacing (Clp only) ~ comment positioning ~ paren- 
theses min/max ~ reserved word case ~ “begin” 
/“end” positioning (Pas only) ~ 30-day money back 
guarentee ~ documentation < 1/2 Ib. 


CleanClipper works with versions 5.0+. Clean- 
Pascal works with TPascal and compatible source 
files. Call 509-328-9542 for a FREE DEMO. 


Invariant Software Credit Card 
P.O. Box 10206 orders only 


Spokane, WA 99209 (800)445-7899 
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Menai Corporation 





i DEVELOPMENT TOOLS 


NEW PARSING TOOL! 


Add reliable, rule-based parsers to your C and 
C++ programs faster than you ever thought 
possible! Speed up program development, 
simplify program maintenance, design friend- 
lier user interfaces. Powerful new notation and 
hassle-free interfaces make AnaGram parsers 
easy to create, modify and maintain. 


Call for Free Trial Copy 
(800) 879-2577 (508) 358-2564 


AnaGram” by Parsifal Software 
P.O. Box 219, Wayland, MA 01778 
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EDUCATION 


B.S. & MLS. 


Tim Otome (oes 


e ALL COURSES HOME STUDY. 
e Approved for tuition reimbursement by leading 


corporations. ras PS 
AMERICAN 


e Most courses interactive. 


e Approved Ada course available. INSTITUTE 
For free information call See 


1-800-767-24270r write: COMPUTER 


2101-DJ Magnolia Ave. 
Suite 200 © Bham, AL 35205 gSCIENCES 


nti 


Be 


FORTRAN 


Indispensable Tools 
For Serious Programmers! 


FORWARN $399 
e Save time and aggravation 


e Find bugs faster 
e Better understand large 
programs 


° ~~ 
For DOS, Also for DOS protected f { 2 i S 
mode. 0S/2, Unix, and VMS. 
30 Day Money Back Guarantee! ENTERPRISES. INC 
; i 


3340 Marble Terrace ¢ Colorado Springs, CO 80906 © (779) 527-1384 
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FORTRAN DEVELOPMENT 
TOOLS $149 


e Find structure in your programs 
e Clean up old, ugly Fortran code 


KKK 
S 


The Complete FORTRAN Programmer’s To 
Create sophisticated state-of-the-art user interfaces for your FORTRAN 
programs. Spindrift’s callable subroutines and functions let you 
© Have data entry screens, dialog boxes, scrolling list boxes 
pull-down menus, push buttons, help panels, etc. All with full 
mouse support. 
© Much more! 281 subroutines and functions for keyboard, 
screen, mouse, DOS control, and hardware status. 
Comprehensive demonstration program shows what you can do and how to do it. 
Now shipping Version 3.0 with all new User Guide. 


PRICE: 16 Bit Compilers - $149 32 Bit Compilers - $289 


Spindrift Laboratories, Ltd. 
116 South Harvard Avenue ¢ Arlington Heights ¢ IL 60005 ¢ USA 
Phone: (708) 255-6909 © FAX: (708) 255-6101 
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GRAPHICS LIBRARIES 


Victor Library v 3.1. Powerful image processing & color 
reduction, bright/contrast, sharpen, outline, resize, over- 
lay, matrix conv., etc. TIFF/BMP/JPEG/PCX/GIF/TGA/bin, 
works with large images without DOS extenders, 
EGA/VGA/SVGA/VESA, up to 16 million colors, 
LaserJet, ScanJet, for MS and Borland, C/C++. Source avail, 
no royal. 


VICTOR LIBRARY for DOS $195 
VICTOR LIBRARY for WINDOWS $295 


470 Belleview St. Louis, Mo 63119 
Call/FAX (314) 962-7833 
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LIBRARIES : 


PGL - Printer Graphics Libraries 


The PGL ToolKit is a set of easy to use 
libraries for generating device independent, 
high resolution graphics output on most popu- 
lar printers. Includes full support for C/C++, 
Fortran, Basic, Pascal, Clipper, & Assembly 
plus 32-bit support for C and Fortran. NO 
ROYALTIES! 


Only $245 (includes all language support) 
Source code available $595! 


AnSoft, Inc. Voice/FAX: (301) 470-2335 
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M-++- Math Libraries for C++ 


1992 Computer Language Productivity Award Winner 


New M++ Version 5.0 provides a complete C++ math library with power- 
ful multi-dimensional array language capabilities. M++ includes 


e LINPACK linear systems code e New Persistent &VirtualArrays 
e EISPACK eigensystem code e Generalized outer operations 
e Expanded signal processing methods © New Visualization module 

© Indexing and sub-array operations © New Advanced math modules 


M++ reduces code size and programming time providing efficient han- 
dling of arrays, matrices and vectors. Available on UNIX, DOS/Windows, 
NT and 05/2 starting as low as $395. 
Dyad Software Corporation 
6947 Coal Creek Pkwy., Ste. 361, Renton, WA 98059-3159 
(206) 637-9426 © Fax (206) 637-9428 
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“, & Windows Programmers - Ta} (kere [eles ale Few 


* DyNGZIP compression 


co) mm \V/l(elce sxe) am uvalaele)w is 


Finally there's an intelligent and easy way to incorporate 
reading and writing of industry standard ZIP files into your 
Windows programs, without having to "shell " to DOS. 


DynaZIP is a set of ROYALTY-FREE DLLs that give you a robust 
API for reading, testing, creating, writing, and updating ZIP 
files. Supports C/C++ and VB; includes source code for a 
high-quality Windows-based ZIP shell, comprehensive 
test/diagnostic tools, and full documentation/help system. 
Versions available for Windows 3.1 and Windows NT. 


Now only $249 w/30-day no-risk guarantee! 
Call today, toll free: (800) 962-2949 


Inner Media. Inc.. Hollis NH USA (603) 465-3216. fax (603) 465-7195 
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All mallocs Are NOT Equal 


SmartHeap” is an ANS! portable malloc and new for 
DOS, Windows, NT, OS/2, UNIX and other platforms. 
Proprietary algorithms deliver speed improvements up 
to 100X versus other commercial mallocs, a igoenee! for 
large heaps in the presence of virtual memory. 
SmartHeap localizes data structures in their own heaps. 
Plus it includes numerous fixed-size and handle-based 
AP|s. Debugging facilities isolate leakage, overwrites, 
double-freeing, wild pointers, and many other errors to 
responsible file/line/pass count. Exceptionally reliable — 
used by a “who's who” of commercial software publish- 
ers. No royalties. Source available. 


Call for FREE White Paper, Benchmarks, 
and Error Reports 


MICROQUILL SOFTWARE PUBLISHING, INC. 


800-441-7822 / 206-525-8218 / FAX 206-525-8309 
Compuserve:70751,2443 Internet:devtools@microaquill.win.net 


Data Structures 


for all Turbo Pascal programmers 


The Data Structures object library provides you with all of 
the data structures you need most: 


V Deques, Stacks, & Queues 

VY Lists (unsorted, sorted, unique key) 

V Trees, Heaps, & Priority Queues 

V Sparse matrices, Huffman encoding, & more! 


Example programs, on-line help, source code, and a 150 page 
manual get you up to speed quick. For Windows and DOS. 


$49 + S&H 
Phone/FAX (617) 232 - 6951 
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Natural Systems 
P.O.Box 968, Brookline, MA 02146 


MARKETING : 


Get Your Software 
To The Right People! 


ay Ba a a a 
If you are selling software to developers or are a software developer 
yourself, you need to be in SoftGuide ’94. Advertise your 
MAC/PC/UNIX software library, algorithm, API, application develop- 
ment tool, or your development expertise at unheard of rates. 
SoftGuide offers an alternative to expensive ad space and focuses 
exclusively on the software development community. Special incentives 
for first time advertisers. 


Software Guides 
1800 Wyatt Drive, Suite 10, Santa Clara, CA 95054 
800-807-7711 or 408-496-5741 
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MARKET YOUR SOFTWARE 


Whether you wish to license your software to an existing 
publisher, or form your own software company, we can help. 
We will provide legal and business services including product 

and market analysis, selection and solicitation of potential 

licensees, license negotiation, drafting and analysis of all 
contracts, incorporation, writing of business plans, and filing 
of financing applications. If your venture is a success we all 
profit, if it fails, you owe us nothing for our services. 


Call or write today. No obligation. Confidential. 
Do not send any software or ideas to us or anyone without a 
signed non-disclosure agreement! 


Michael Norman Saleman, Attorney at Law 


Rayman & Associates Consulting 
15910 Ventura Blvd., Suite 801A, Encino, CA 91436 


v: 818/379-8770 f: 818/379-8780 CIS: 71401,1653 
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NETWORK 


Start small, grow as you do 
* Peer to peer LAN to 250 nodes 

* $75 total software cost/LAN, not node! 

* Use Ethernet or Arcnet for speed 

* or Zero-slot via serial/parallel/modem 

* Share most anything in DOS or Windows 

* Needs only 40K of ram 


Information Modes 
Drawer F, Denton TX 76202 
817-382-7407 FAX 
1-800-628-7992 Orders 
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PROLOG TOOLS 


Discover the Magic 


of Prolog...starting at $49 


DOS, 16 and 32-bit interpreter, $49. 
Interactive tutorial, $75. Edinburgh- 
standard development system, $149 
Expert systems tutorial w/src, $82. 


FREE Catalog « MC/Visa 
Moneyback Guarantee 


Amziod 40 Samuel Prescott « Stow, MA 01775 
508/897-7332 fax -2784 amziod @world.std.com 
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RECRUITMENT 


Japanese-fluent Professionals! 
Teach our week-long technical 
course in Japan 
¢ Software Development/Technical Management 

¢ Object-Oriented Analysis & Design 

¢ Programming in C, C++ 

¢ Open Systems, Client Server Systems 
¢ Datacomm, LAN’s, Novell Netware 
Send Resumé to Michael Lopez at: 


Learning Group International 
6053 W. Century Blvd. LA, CA 90045 
Fax : (310) 645-4762 Voice : (310) 417-9700 
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RECRUITMENT 


FREE Bulletin Board 
413-549-8136 (8-N-1) 
Direct dial. Baud rates to 14,400. 

If you have access to a modem, we invite 
you to navigate our listings of hundreds 
of today’s hottest search assignments 
nationwide, plus forums and career guides. 


Software and IS jobs 


Allen Davis & Associates, National Technical Search 


PO Box 2007 * Amherst, MA 01004-2007 
tel: 413-549-7440 ¢ fax: 413-549-7542 


Call or write in confidence. Client companies pay all fees. 
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ATLANTA'S 


WINDOW FOR 
WINDOWS PRO'S 


For over a decade, leading S.E. com- 
panies have relied on MATRIX to pro- 
vide the talent to help them develop 
tomorrow's software. We currently 
have immediate openings for 20+ 
Window's professionals with salaries 
from the mid $50s to $90s and reloca- 
tion assistance. 


Our staff of 16 placement specialists will 
ote |F-Yo Ma Co ene) ii] amtZe)0 m= la mr-(ere10 | ¢-1(- i= toe 
sessment of opportunities awaiting you 
in Atlanta and placement assistance 
without fee. 


Call 404-393-9933; Fx: 404-668-0384 


MATRIX 


THE HUMAN FACTOR 


aM Roms od =) 610 01>)(=) am @1=)0)0=) 0 wd f= (01-9 
SIU (ow-sol OW AN lato MR CT-WCO Geom 
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SECURITY 


Since 1986, thousands of companies worldwide 
have chosen Az-Tech Software as partners in 
their fight against Software Pirates. Why? 
Because we offer you proven leaders: 
EVERLOCK software Copy Protection 


Option Board Safe—Remote Registration 
New CPU LOCK-CD ROM LOCK and more 


EVERKEY HARDWARE LOCKS 
Call fora FREE Demo 
(800) 227-0644 


201 East Franklin, Richmond, MO 64085 
(816) 776-2700 Fax (816) 776-8398 
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SOFTWARE COPY PROTECTION 


We build quality, security and affordability into our LTLOCK 
copy protection software. Evaluate, compare and see what 
we are offering: 

* Installs easily on your IBM-PC Software 

¢ Defeats all disk copy software 

¢ Requires NO special devices or disks 

¢ MSDOS 6 compatible 

¢ Customize options available 
Evaluation disk (5 counts) $25. 
Starter kit (100 counts) $145. 
unlimited counts kit also available 
L-Tech Corporation 
2460 Lemoine Ave 
Fort Lee, NU 07024 
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Tel: 201-585-8820 
Fax: 201-585-9022 


SOFTWARE SORTING 


NO ROYALTIES 


OmniSort Sorts, Merges, Selects, and Formats 
DOS, Btrieve and dBase files FAST. Runs as a 
stand-alone program or links with your Assembler, 
Basic, C, Cobol, Fortran & Pascal programs. 
Supports unlimited keys and four gigabyte files. 


Regular $129 Special $99 until 3/31/94 


803 786-7367 


Omniware 
501 Kinsler Road, Blythewood, SC 29016 
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Opt-Tech Sort 


High Performance Sort/Merge/Select Utility. Run from the 
command line or Call as a subroutine to your programs. 
Supports most languages and filetypes. Unlimited file size, 
multiple keys and much more! New Version 5.0 includes 
More Speed and More Features! 


MS-DOS or Windows $149 — 0S/2 or Unix $249 


(702) 588-3737 


Opt-Tech Data Processing 
P.O. Box 678 * Zephyr Cove NV 89448 
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SOURCE CODE BROWSER 


C & C++ browsing and analysis 
with cross referencing in your 
DOS, OS/2 or Windows editor! 


The original and the best! 
Western Wares | windows | 


(303) 327-4898 
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SOURCE CODE ESCROW 


SOURCE CODE ESCROW 


It’s finally here — A flexible source code escrow 


service for independent developers. 
¢ Guarantee future support 
e Enhance your professional image 
e You retain copyright 
Call today for a complete information package! 


AMERICAS 
CORPORATION 


821 Fir Street ¢ Sandpoint, ID 83864 
1°¢800°569°7569 © FAX 208e265¢4191 
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TOOLS 


TIRED OF MORE?? 


Tired of watching vital information scroll off your screen? 
Wish there were more to life than the “more” command? 


Introducing TSCRIPT™ the transcripting software from 
Green Valle Software. TSCRIPT allows you to scroll back 
through program output for convenient viewing. Or select a 
portion of the program output for printing or output to a file. 


TSCRIPT works with existing DOS commands and can be 
built into your software. Don’t delay, send for your copy of 
TSCRIPT today - only $29.95 + tax. 


Green Valle Software 
P.O. Box 28988, San Diego, CA 92198-0988 
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TOOLS 
C and C++ DOCUMENTATION TOOLS 


Graphic-tree of caller/called function 
hierarchy, function/files index, function cross-reference. 


Creates/inserts comment-blocks (func- 
tions/identifiers used) for each function. 


59) Calculates path ella e 
counts lines with comments, code, and ‘C’ statements. 


Lists and action-diagrams, or reformats 
source into user selected standard formats. 


Creates ead al ce palamerer 
cross-reference, C++ class hierarchy tree. 


Special: C-DOC ($199) All 5 in 1 DOS (<15,000 lines) 
C-DOC Professional ($299) DOS, OS2, Windows 
Processes 150,000+ lines, enhanced 3-ring binder. 


SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Voice/Fax: (416) 858-4466 
Mississagua, ONT Demos/BBS: (416) 858-1916 
Canada L5N-4M1 
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UTILITIES 


AeSORT Sort Merge/Select 
ULTIMATE SORT SPEED 


New Criteria for the words ‘FAST sort’ 

Up to 12 TIMES faster than others, 10k size. 
Versatile, Easy. DOS exe, batch or call subrtn 
from popular languages. Mult keys & lengths, 
Ascn/Dscn, output recs, keys or inx’s. Fixed, 
xbase, etc. Also powerful Merge/Select. $159. 


AeSORT Inc. 
4070 E. Pueblo, Phoenix, AZ 85040 
(602) 437-2867 
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VERSION CONTROL 


Winner Microsoft Systems Journal’s competitive 
review of VCS’s (PVCS, TLIB, CCC etc.) 


“My favorite is SourceSafe, it does what you want.” 


Winner Computer Language’s Productivity Award 


“SourceSafe’s ease of use belies it’s power.” 


Join Intel, Novell, Oracle, Motorola and American Airlines 
Save a minimum of 5 hours per week with SourceSafe. 
The only object oriented VCS for all platforms. 


Call now for information or to order 


1-800-364-5467 Fax: 919-848-0307 
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WINDOWS iy 


: < y 


Why use a language from the 70's for applications of the 
90's?Lingo source code is fully portable across different 
platforms. Contact us 24 hours a day for more 
information. 


LINGO LANGUAGE ¢ Phone 61(9) 485 7830 © Fax 61(9) 316 2873 
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Emacs for Windows 


WinEmacs is a fully functional Windows 3.1 version of the industry 
standard program editor Gnu Emacs, version 19.3. 
WinEmaCs HAS THESE EXTENDED FEATURES: 

Separate buffers in different windows © Clipboard support 

e Menu and drop-down menu bar © Scroll bars 

¢ Multiple font size and type support + © DDE and OLE support 

¢ Cut and paste mouse support e Binds any arbitrary combination 

¢ Support for text and Binary files of a key and key modifiers to 

e Support for foreign keyboards Emacs Lisp code 
Contact Pearl Software at pearl@netcom.com (e-mail) (510) 273-9795 (voice) 
or (510) 839-9820 (fax) for more information. Supported version costs $199. 

CALL 1-800-WIN-EMAC 
— WE ALSO PROVIDE EMACS CONSULTING SERVICES — 


Pearl Software - 320 Lenox Avenue, Oakland, CA 94610 
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(continued from page 162) 

Map Overlay and GPS Support add- 
on libraries. These tools can be used 
in conjunction with CD-ROM-based 
regional and metropolitan map sets, 
also available from Horizons. 

The Map Overlay Library allows you 
to create object-oriented databases us- 
ing objects such as points, lines, ellipses, 
polygons, and so forth. These objects 
can be geo referenced to the underly- 
ing map database and application- 
specific data. 

The Developer’s Kit supports Mi- 
crosoft C and Borland C++. The three- 
library kit sells for $1739.00. You can 
also buy the libraries separately. Read- 
ef Service No,.25. 

Horizons Technology 
3990 Ruffin Rd. 

San Diego, CA 92123-1826 
800-828-3808 


Visual Edge’s Visual Action Toolset is 
a collection of tools that incorporates 
Display PostScript and the OSF/Motif 
widget set for creating document in- 
terfaces which allow a PostScript im- 
age to be used as an interface element. 
Additionally, any standard interface el- 
ement can be incorporated into a 
PostScript image or document. The tool 
set uses a layered approach to devel- 
opment that parallels X application de- 
velopment. The Visual Action Widget 
Set, comprised of rendering widgets, 
see-through controls and a Visual Man- 
ager, is analogous to Motif. In this lay- 
er, rendering widgets give the ability 
to display a PostScript image and to 
control interface graphics, see-through 
controls enable the developer to cre- 
ate widgets with transparent back- 
grounds, and Visual Manager widgets 
control the display and position of 
child widgets. 

The Visual Action Toolset Framework, 
analogous to the Xt toolkit, provides the 
functionality common to VA widgets. 
The framework can be used to subclass 
existing VA widgets or to create new 
widget classes. A Display PostScript 
Client Library, similar in nature to Xlib, 
provides a C language interface to the 
Display PostScript system. 

The Visual Action Toolset sells for 
$2500.00. It supports UNIX and Motif 
on SunOS 4.1.3, AEX 3.2.4, and SGI IRIX 
5.1.1. Reader service no. 26. 

Visual Edge Software 
3950 Cote Vertu, Suite 100 
St-Laurent, PQ 

Canada H4R 1V4 
514-332-6430 


Procase Corporation is shipping Smart- 
System 3.0, a software tool that helps 
programmers understand and fix large 
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amounts of unfamiliar source code by 
graphically displaying code structure, 
providing information about errors and 
dependencies, and performing impact 
analysis. SmartSystem is distinguished 
by its large capacity (able to handle C 
programs in excess of 1 million lines of 
code) and robustness (able to handle 
code that is incomplete, does not com- 
pile, or has errors). It can handle many 
dialects of C, including code targeted 
for many UNIX platforms and embed- 
ded systems, providing both graphical 
and textual views of code, using a va- 
riety of formatting styles. 

Version 3.0 runs on Sparc/SunOS, 
Sparc/Solaris, HP9000/700, and IBM 
RS/6000 platforms. The major new func- 
tionality is the addition of a makefile an- 
alyzer to facilitate getting started in build- 
ing the code database. It also provides 
additional code comprehension capa- 
bilities in the Call Graph display, by 
showing dependencies involving glob- 
al data and function pointers Gin addi- 
tion to showing function and library 
calls, as supported in the previous ver- 
sion). There are also mechanisms for 
uncovering undefined preprocessor 
macros. Reader service no. 27. 
Procase Corporation 
2694 Orchard Parkway 
San Jose, CA 95134 
408-321-3951 


Visual SlickEdit, an updated version of 
the venerable SlickEdit programmer’s 
editor from MicroEdge, is available for 
Windows and Windows NT. Visual 
SlickEdit is a configurable editor that 
uses an object-oriented, C-style macro 
language (source code for the macro 
language comes with the editor) and a 
built-in dialog editor. The dialog editor 
lets you create event-driven dialog box- 
es. Additional controls the tool provides 
include spin, gauge, drive list, file and 
directory list, and the like. The editor 
also makes use of a technology Mi- 
croEdge calls “clipboard inheritance,” 
which provides inheritance of code past- 
ed to the clipboard. 

Visual SlickEdit, which sells for 
$295.00, includes Brief and Emacs em- 
ulation and provides special support for 
most compilers and languages. The ed- 
itor is available for Windows 3.1 and 
Windows NT on Intel, Mips, and Alpha 
machines. Reader service no. 28. 
MicroEdge 
P.O. Box 18038 
Raleigh, NC 27619-8038 
919-790-1691 


Intel and Microsoft have jointly an- 
nounced an update to the Advanced 
Power Management (APM) Interface 
specification, which is designed to in- 





crease battery life for portable and oth- 
er low-power consumption computers 
based on Intel platforms. Originally re- 
leased in January 1992, APM allows the 
operating system to communicate 
through ROM BIOS to instruct system 
resources to power down during peri- 
ods of nonuse. APM is already sup- 
ported by the Plug and Play BIOS spec- 
ification. New features of APM 1.1 
include new power-management func- 
tions to enhance cross-platform com- 
patibility, enhancements to the sus- 
pend/pause scheme for improved 
communication between the operation 
system and BIOS, and a BIOS-com- 
patibility test so that BIOS developers 
can verify compliance with the speci- 
fication. 

Copies of the APM 1.1 BIOS Interface 
specification are available through the 
Intel Literature Center, order #241704. 
The document is also available on 
CompuServe through Intel Access, the 
company’s developer-support service. 
Alternatively, the specification can be 
obtained through Microsoft’s Hardware 
Vendor Relations Group, or through the 
Plug and Play forum on CompuServe. 
The APM 1.1 BIOS-compatibility test is 
available to OEMs and BIOS-developers 
through Intel’s General Support Group 
(800-628-8686). Reader service no. 29. 
Intel Literature Center 
800-548-4725 
Microsoft Hardware Vendor Relations 
206-882-8080 


WidgetKit/CUA ’91 is an add-on for 
Objectshare’s WindowBuilder Pro/V, 
an interface builder that works with 
Small-talk/V for OS/2. WidgetKit/CUA 
91 adds support for OS/2-style user- 
interface elements as defined by the 
Common User Access (CUA) ’91 spec- 
ification. The tool includes various 
controls, including a notebook, slid- 
ers, spin buttons, containers, and value 
sets. Specialized editors are used for 
direct access to each of the control’s 
attributes. The notebook control uses 
caching to enhance performance for 
large notebooks. Widget-Kit/CUA ’91 
includes full Small-talk/V OS/2 source 
code, and there are no royalties or 
run-time fees for applications devel- 
oped with WindowBuilder Pro. The 
company plans to release Windows 
and Win32 versions of the product 
early in 1994. 

WidgetKit/CUA ’91 sells for $295.00. 
Reader service no. 30. 
Objectshare Systems 
5 Town & Country Village, Suite 735 
San Jose, CA 95128-2026 
408-727-3742 
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SWAINE’S FLAMES 





Swaine’s World 


don’t need this aggravation. 
: The Wall Street Journal has been running a series on Home Workers, people like me who 

work out of a home office. Or “home/office,” as some punctuate it. A home office is a den or 
bedroom converted to business purposes. A home/office is a home taken over by the 
paraphernalia of one’s work. I have a home/office. 

Anyway, the first story in the series didn’t paint a very flattering picture of us Home Workers. 
Many of us are torn by feelings of inadequacy, the Journal reported, working late into the night 
to overcompensate. Eventually, we start talking to our dogs. It didn’t get any better: The second 
story in the series was headlined, “Home Workers Are a Bunch of Slobs.” 

The Home-Worker-as-Slob motif also figured in a recent contest sponsored by Home Office 
Computing magazine, which awarded a prize for the messiest home office. Hah. Big joke. 

It’s not a joke. 

It’s a lifestyle choice. 

Besides, as I told Zelda, my Labrador retriever, it’s not fair to single out us Home Workers. 
There are plenty of slobs among— to choose an example completely at random — computer- 
magazine editors. I could tell you stories. Or programmers. I’ve seen some of your offices. Or at 
least as much of them as is visible under the mounds. What color is your carpet, hmmm? 

But as somebody once said, “success is what we make of the mess we have made of things.” 
I'd give you the exact quote, but that would entail finding my book of quotations in this mess. 

Deciding to make some success out of mess, I cleaned up part of my home/office. The result: 
my new basement/library/studio, an immaculate and cozy nook lined with books and furnished 
with comfy chairs and footstools— and a video camera and microphone. The ideal setting for 
conducting video interviews. 

I call it, “Swaine’s World.” 

I haven’t actually done a video interview yet, but I imagine it would go something like this: 





Cast: | Swaine’s World! Swaine’s World! Runtime! Execute! 

Swaine: All right! Parity on, Corbett! 

Corbett: Parity on, Swaine! 

Swaine: All right. We’re going to skip the gratuitous morph and go right to the totally awesome 
stuff. Our first guest is David Gergen, newly appointed Director of Spin Control for 
Microsoft System Software Division. 

Corbett: He’s our only guest, Swaine. 

Swaine: Too true, Corb. All right. Give it up for Microsoft, folks, if you haven’t already. 

Gergen: Thank you. You’re too kind. This is too much. Thank you. No, really. You’re too kind. 

Swaine: Hello-o? Nobody’s clapping, Dave. Are you mental? 

Corbett: Mr. Gergen, given that OpenDoc, unlike OLE, is an open protocol, is reputedly easier to 
develop for than OLE, and is a superset of OLE, why should a developer write for OLE? 

Gergen: Because OLE is the standard, dorkface. 

Corbett: Oh. I’m sorry. 

Gergen: I'll let it go this time. 

Swaine: So, Dave, have you heard this one? How many Microsoft programmers does it take to 
screw in a light bulb? 

Gergen: Stop right there, Swaine. Microsoft bought all rights to that joke last year. If you tell it on 
the air you'll owe us $12,000 in royalties. 

Swaine: Exsqueeze me? Overflow. Ground fault. Receiver has disconnected. Beeeeeep. That’s all 
the time we have, folks. Don’t screw up and miss our next show, when we'll interview 
user-interface designer and former rock musician, Nigel “But-this-knob- goes-up-to- 
eleven” Tufnel. 


J LaD Sera: 


Michael Swaine 
editor-at-large 
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C, C++ and BASIC programmers, 
now you get much more than 


xBase com 


housands of programmers have 
already discovered how to get dBASE, 
FoxPro and Clipper compatibility from 
their favorite language and hardware 
platform. For example, one customer 
has C programs running on PC and Sun 
workstations sharing data with 
concurrently running FoxPro for 
Windows applications. You see, 
CodeBase technology is simply the best 
way to add multi-user xBase compatible 
DBMS power to C, C++, or BASIC. 


You still get high speed & small size 
CodeBase users really appreciate our 
small executable size. Unlike SQL 
engines which are a Meg or so in size, 
CodeBase 5.1 EXE’s can be as small as 
45K! You'll also like the speed—with 
our Intelligent Queries you get the 
execution speed of C plus stunning 
query performance from our smart use 
of available index information. 


Introducing CodeControls 


Now formatted data entry in Windows is as easy 
as point & click! 





Introducing the new CodeControls, a unique set 
of data-aware custom controls. Now simply drop 
them into your Windows applications via your 
favorite visual interface builder. 


NEW-You get formatted data entry 


Experienced Windows programmers 
know formatted data entry is difficult 


to program under Windows. But with 
our new CodeControls, you can simply 
'Point & Click' to design data entry 
windows for date, numeric, and character 
information—formatted just the way you 
want it. 


NEW-Data-aware controls 


Our custom controls are data-aware, so 
now you can easily build a scrolling list 
box that's tied to a data file, or look up 
matching combo box entries—even as the 
user types. 


Introducing CodeReporter 2.0 
Now use the new Instant Report Wizard to create 
a ane: of reports—instantly. 


ee - CadeReporter 2.0: AD6 oo Ae 


le Align Edit View Report Relation Group a Qbject Styte 
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Introducing the new CodeReporter 2.0, our inter- 
active xBase report writer. We re-designed it with 
developers in mind, but end-users will love it. 


NEW-You get instant reports 

Use our new Instant Report Wizard to 
quickly create a wide variety of 
reports—in an instant, then easily refine 
them as necessary, or let your end users 
build their own special reports! 


NEW-You get drag & drop 


We've added drag & drop capabilities to 
CodeReporter, so regardless of whether 
you want data, totals, or text, simply drop 
a report object onto your layout screen. 


patible DBMS power. 


NEW-You get interactive queries, 
sorts, & relations 


Use CodeReporter to | 
visually design reports | 
easier than ever. For | 
example, you can 
quickly build query anid sort 
expressions using our calculator-style 
expression builder. In addition, you can 
easily relate data files together using 
our graphical relation builder. 










‘There's never been a better time to buy 
into CodeBase technology. You get 
complete xBase compatibility, full 
DBMS power, plus an interactive report 
writer and a set of unique data-aware 


custom controls for Windows.” 
-Ken Sawyer, President, Sequiter Software 


Buy One, 
Get Two FREE. 


Now when you buy any one of our xBase 
library products: CodeBasic, CodeBase+t, 
or CodeBase (for the language of your choice), 
you'll get both the new CodeReporter 2.0 
AND the new CodeControls absolutely 
FREE -for a limited time only. 


To Order Now Call 
413-437-2410 


Unconditional 90-Day Money-Back Guarantee 


SEQUITER | 


SOFTWARE INC. 


FAX 403943692999 
UK Tel. +44-81-317-4321 
France +33.20.24.20.14 
P.O. Box 575 Newmarket NH 03857-0575 














©1993 Sequiter Software, Inc. All rights reserved. CodeBase, CodeBase++, CodeBasic, CodeReporter, and CodeControls are trademarks of Sequiter Software Inc. All other product names mentioned herein are trademarks of their respective companies. 
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Borland C++ gives you so much more? 
The highest quality fourth-generation 
tool set. A fully customizable and open 
desktop. The ability to target 
16- and 32-bit 
Windows simul- 
taneously. And, 
of course, it’s 
“visual.” 
Only Borland C++ 
gives you a fully 
integrated profes- 
sional editor featuring BRIEF” tech- 
nology, powerful Turbo Debugger® Gx, 
and integrated C and C++ VBX control 
support. 


An environment to die for 


Borland C++ 4.0 takes the bureaucracy 
out of development. With the visual 
Project Manager and its multi-target 
capabilities, even the most complex 
projects are handled automatically. 


The flexibility of AppExpert actually 


Why settle for ordinary visual when new 


Visual is just the beginning 


generates much of your application for 
you. TargetExpert, ClassExpert, Dialog- 
Expert, and Resource Workshop™ 
streamline the tasks of setting up and 


customizing your applications. 


A true C++ implementation 
that's years ahead 


Languages evolve for a good reason— 
sO programmers can realize ever- 
increasing productivity and safety of 
code. That’s why Borland is the first to 
bring important new enhancements to 
the C++ language, like full support 
for templates, exception handling, 


and Run-time Type Information. And 








have. After all, if your compiler is only 
visual, it’s just a facade. Get new 
Borland C++ 4.0 for Windows and DOS 


now. 






Borland C++ owners 


Upgrade Now! 


7 Ag% 


(Suggested 
Other C++ owners 


list price 
$499 










$499.95) 


90-day, money-back guarantee! 


Borland C++ includes ObjectWindows™ See your dealer or call now, 


Library (OWL) 2.0—the world’s most 
popular framework. 

Borland C++ is the world-standard 
C++ because it’s the easiest to use, 
yet has power to spare for the most 
complex tasks. If you’re serious about 
C++ programming, new Borland C++ 


4.0 is the environment you’ve got to 


1-800-336-6464, ext. 7030 


In Canada call, 1-800-461-3327. 
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Borland 


Power made easy” 
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